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OVERVIEW 


consists of the complete MS-DOS 2.1 Reference 
Manual. Like Volume I of this Kit, which 
discusses Macro Assembler and the Utilities, this 
manual is written for the high-level systems 
programmer. 


Chapter One -~- System Calls — is the main section 
in this Volume. This chapter is divided into such 
areas as Programming Considerations, the File 
Control Block (FCB), System Call Description, 
Interrupts (ranging from 20H to 27H), and Function 
Requests (ranging from 00H to 57H). Other 
chapters are devoted to: 


o MS-DOS Device Drivers, including a discussion 
of device headers, and instructions for 
creating and installing the drivers; 


o MS-DOS Technical Information, such as 
initialization, the command processor, and disk 
allocation; 


o MS-DOS Control Blocks and Work Areas; and 


Oo .EXE File Structure and Loading. 


1. SYSTEM CALLS 


1.1 INTRODUCTION 


MS-DOS provides two types of system calls: 
interrupts and function requests. This chapter 
describes the environments from which these 
routines can be called, how to call them, and the 
processing performed by each. 


1.2 PROGRAMMING CONSIDERATIONS 


Having the system calls mean you don't have to 
invent your own ways to perform these primitive 
functions. Consequently, it is easier to write 
machine-independent programs. 


1.2.1 CALLING FROM MACRO ASSEMBLER 


The system calls can be invoked from Macro 
Assembler simply by moving any required data into 
registers and issuing an interrupt. Some of the 
calls destroy registers, so you may have to save 
registers before using a system call. The system 
calls can be used in macros and procedures to make 
your programs more readable; this technique is 
used to show examples of the calls. 
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1.2.2 CALLING FROM A HIGH-LEVEL LANGUAGE 


The system calls can be invoked from any high- 
level language whose modules can be linked with 
assembly-language modules. 


Calling from MS-BASIC: Different techniques are 
used to invoke system calls from the compiler and 
interpreter. Compiled modules can be linked with 
assembly-language modules; from the interpreter, 
the CALL statement or USER function can be used to 
execute the appropriate 8086 object code. 


Calling from MS-Pascal: In addition to linking 
with an assembly-language module, MS—Pascal 
includes a function (DOSXQQ) that can be used 
directly from a Pascal program to call a function 


request. 


Calling from MS-FORTRAN: Modules compiled with 
MS-FORTRAN can be linked with assembly—language 
modules. 

1.2.3 RETURNING CONTROL TO MS-DOS 


Following completion of your program, control can 
be returned to MS-DOS in any of four ways: 


1. Call Function Request 4CH 


MOV AH, 4CH 
INT 21H 


This is the preferred method. 


2. Call Interrupt 20H: 
INT 20H 


3. Jump to location 0 (the beginning of the 
Program Segment Prefix): 


JMP. 0 


Location 0 of the Program Segment Prefix 
contains an INT 20H instruction, so this 
technique is simply one step removed from the 
first. 


4. Call Function Request OOH: 


MOV AH,O00H 
INT 21H 


This causes a jump to location 0, so it is 
simply one step removed from technique 3, or 
two steps removed from technique 1. 


1.2.4 CONSOLE AND PRINTER INPUT/OUTPUT CALLS 


The console and printer system calls let you read 
from and write to the console device and print on 
the printer without using any machine-specific 
codes. You can still take advantage of specific 
capabilities (display attributes such as 
positioning the cursor or erasing the screen, 
printer attributes such as double-strike or 
underline, etc.) by using constants for these 
codes and reassembling once with the correct 
constant values for the attributes. 


1.2.5 DISK I/O SYSTEM CALLS 


Many of the system calls that perform disk input 
and output require placing values into or reading 
values from two system control blocks: the File 
Control Block (FCB) and directory entry, 


1.3 FILE CONTROL BLOCK (FCB) 


The Program Segment Prefix includes room for two 
FCBs at offsets 5CH and 6CH. The system call 
descriptions refer to unopened and opened FCBs. 

An unopened FCB is one that contains only a drive 
specifier and filename, which can contain wild 
card characters (* and ?). An opened FCB contains 
all fields filled by the Open File system call 
(Function OFH). Table 1-1 describes the fields of 
the FCB. 


Table 1-l: Fields of File Control Block (FCB) 


SIZE OFFSET 
NAME (BYTES) HEX DECIMAL, 

Drive number 1 00H 0 
Filename 8 01-08H 1-8 
Extension 3 09-0BH 9-11 
Current block 2 OCH, ODH 12,13 
Record size : 2 OEH , OFH 14,15 
File size 4 10-13H 16-19 
Date of last write 2 14H,15 20,21 
Time of last write 2 16H,17H 22,23 
Reserved 8 18-1FH 24-31 
Current record i 20H 32 
Relative record 4 21-24H 33-36 
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1.3.1 FIELDS OF THE FCB 


Drive Number (offset 00H): Specifies the disk 
drive; 1 means drive A: and 2 means drive B:. If 
the FCB is to be used to create or open a file, 
this field can be set to 0 to specify the default 
drive; the Open File system call Function (0FH) 
sets the field to the number of the default 
drive. 


Filename (offset 01H): Eight characters, left- 
aligned and padded (if necessary) with blanks. If 
you specify a reserved device name (such as CON), 
do not put a colon at the end. 


Extension (offset 09H): Three characters, left- 
aligned and padded (if necessary) with blanks. 
This field can be all blanks (no extension). 


Current Block (offset OCH): Points to the block 
(group of 128 records) that contains the current 
record. This field and the Current Record field 
(offset 20H) make up the record pointer. This 
field is set to 0 by the Open File system call. 


Record Size (offset OEH): The size of a logical 
record, in bytes. Set to 128 by the Open File 
system call. If the record size is not 128 bytes, 
you must set this field after opening the file. 


File Size (offset 10H): The size of the file, in 
bytes. 


The first word of this 4-byte field is the low- 
order part of the size. 


Date of Last Write (offset 14H): The date the 
file was created or last updated. The year 
(excluding the century), month, and day are mapped 
into two bytes as follows: 


Offset 154 

ped ae ei ee ae le ae 

15 9 8 BIT 
Offset 14H 
|mM|M|[mM|[D|D|[D|pD|D| 

7 5 4 0 BIT 


Time of Last Write (offset 16H): The time the 
file was created or last updated. The hour, 
minutes, and seconds are mapped into two bytes as 
follows: 


Offset 17H 
|}H|H|H|H|H|M|[M|M| 

15 11 10 8 BIT 
Offset 16H 
|mM([mM|mM|[s|s|s|s|s| 

7 5 4 0 8 6BIT 


Reserved (offset 18H): These fields are reserved 
for use by MS-DOS. 


Current Record (offset 20H): Points to one of the 
128 records in the current block. This field and 
the Current Block field (offset OCH) make up the 
record pointer. This field is not initialized by 
the Open File system call. You must set it before 
doing a sequential read or write to the file. 


1-7 


Relative Record (offset 21H): Points to the 
currently selected record, counting from the 
beginning of the file (starting with 0). This 
field is not initialized by the Open File system 
call. You must set it before doing a random read 
or write to the file. If the record size is less 
than 64 bytes, both words of this field are used; 
if the record size is 64 bytes or more, only the 
first three bytes are used. 


Note: If you use the FCB at offset 5CH to the 
Program Segment Prefix, the last byte of the 
Relative Record field is the first byte of the 
unformatted parameter area that starts at offset 
80H. This is the default Disk Transfer Address. 


1.3.2 EXTENDED FCB 


The Extended File Control Block is used to create 
or search for directory entries of files with 
special attributes. It adds the following 7-byte 
prefix to the beginning of the FCB: 


SIZE OFFSET 
NAME (BYTES) (DECIMAL) 
Flag byte (255, or FFH) l ~7 
Reserved 5 -6 
Attribute byte: 1 -1 
02H = Hidden file 
04H = System file 


1.3.3 DIRECTORY ENTRY 
A directory contains one entry for each file on 


the disk. Each entry is 32 bytes; Table 1-2 
describes the fields of an entry. 


Table 1-2: Fields of Directory Entry 


SIZE OFFSET 

NAME, (BYTES) HEX DECIMAL 
Filename 8 00-07H 0-7 
Extension 3 08-0AH 8-10 
Attributes 1 OBH Ll 
Reserved 10 OC-15H 12-21 
Time of last write 2 16H, 17H 22,23 
Date of last write 2 18H, 19H 24,25 
Reserved 2 JAH, 1BH 26,27 
File size 4 1C-1FH 28-31 
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1.3.4 FIELDS OF THE FCB 


Filename (offset 00H): Eight characters, left- 
aligned and padded (if necessary) with blanks. 
MS-DOS uses the first byte of this field for two 
special codes: 


OOH (0) End of allocated directory 
ESI (229) Free (that is, unused) directory entry 


Extension (offset 08H): Three characters, left- 
aligned and padded (if necessary) with blanks. 
This field can be all blanks (no extension). 


Attributes (offset OBH): Attributes of the 
directory entry: 


VALUE 
HEX — BINARY DEC MEANING 


01H 0000 0001 1 = Read-only file 

02H 0000 0010 2 _ £Hidden file 

04H 0000 0100 4 System file 
(These attributes are 
changeable with CHGMOD) 

08H 0000 1000 8 This directory entry is the 
Volume's ID 

QAH 0001 0000 10 #£This directory entry isa 
sub-directory's name 

20H 0020 0000 32 #£«®Archive Bit (set when a file 
is written to, reset via 
function 43H) 
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Reserved (offset OCH): Reserved for MS-DOS. 


Time of Last Write (offset 16H): The time the 
file was created or last updated. The hour, 
minutes, and seconds are mapped into two bytes as 
follows: 


Offset 17H 
|H|H|H|H|[H[M[M{[M| 
15 11 


Offset 16H 
[wl M | MPs s |-s | s)-s | 
7 5 4 0 


Date of Last Write (offset 18H): The date the 
file was created or last updated. The year, 
month, and day are mapped into two bytes as 
follows: 


Offset 19H 
ee eae [ee [iad ae icv oe, 
15 98 


Offset 18H 
[M|[mM|M|D|{D|]D|D|D| 
7 5 4 0 


File Size (offset 1CH): The size of the file, in 
bytes. The first word of this 4-byte field is the 
low-order part of the size. 
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1.4 SYSTEM CALL DESCRIPTIONS 


Many system calls require that parameters be 
loaded into one or more registers before the call 
is issued; most calls return information in the 
registers (usually a code that describes the 
success or failure of the operation). The 
description of system calls 00H-2EH includes the 
following: 


o A drawing of the 8088 registers that shows 
their contents before and after the system 
call. 


© A more complete description of the register 
contents required before the system call. 


o A description of the processing performed. 


o A more complete description of the register 
contents after the system call. 


o An example of its use. 


The description of system calls 2FH-57H includes 
the following: 


o A drawing of the 8088 registers that shows 
their contents before and after the system 
call. 


o A more complete description of the register 
contents required before the system call. 


o A description of the processing performed. 
o Error returns from the system call. 


o An example of its use. 
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Figure 1-1 is an example of how each system call 
is described. Function 27H, Random Block Read, is 
shown. 


Figure 1-1: Example of System Call Description 


Call 
AH = 27H 
DS :DX 
Opened FCB 
CX 
Number of blocks to read 
Return 
AL 
0 = Read completed successfully 
1 = EOF 
2 = End of segment 
3 = EOF, partial record 


CX 
Number of blocks read 


1.4.1 PROGRAMMING EXAMPLES 


A macro is defined for each system call, then used 
in some examples. In addition, a few other macros 
are defined for use in the examples. The use of 
macros allows the examples to be more complete 
programs, rather than isolated uses of the system 
calls. All macro definitions are listed at the 
end of the chapter. 


The examples are not intended to represent good 


programming practice. In particular, error 
checking and good human interface design have been 
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sacrificed to conserve space. You may, however, 
find the macros a convenient way to include system 
calls in your assembly language programs. 


A detailed description of each system call 
follows. They are listed in numeric order; the 
interrupts are described first, then the function 
requests. 


Note: Unless otherwise stated, all numbers in the 
system call descriptions -—- both text and code —- 
are in hex. 


1.5 XENTX-COMPATIBLE CALLS 


MS-DOS 2.1 supports hierarchical (i.e., tree- 
structured) directories, similar to those found in 
the Xenix operating system. (For information on 
tree-structured directories, refer to Volume I of 
this Option.) The following system calls are 
compatible with the Xenix system: 


Function 39H Create Sub-Directory 

Function 3AH Remove a Directory Entry 
Function 3BH Change the Current Directory 
Function 3CH Create a File 

Function 3DH Open a File 

Function 3FH Read From Fileé/Device 
Function 40H Write to a File or Device 
Function 41H Delete a Directory Entry 
Function 42H Move a File Pointer 

Function 43H Change Attributes 

Function 44H I/O Control for Devices 
Function 45H Duplicate a File Handle 
Function 46H Force a Duplicate of a Handle 
Function 4BH Load and Execute a Program 
Function 4CH Terminate a Process 

Function 4DH Retrieve the Return Code of a Child 


1-14 


There is no restriction in MS-DOS 2.1 on the depth 
of a tree (the length of the longest path from 
root to leaf) except in the number of allocation 
units available. The root directory will have a 
fixed number of entries. For non-root 
directories, the number of files per directory is 
only limited by the number of allocation units 
available, 


Pre-2.1 disks will be readable by MS-DOS 2.1 and 
appear as having only a root directory with files 
in it and no subdirectories. 


Implementation of the tree structure is simple. 
The root directory is the pre-2.1 directory. 
Subdirectories of the root have a special 
attribute set indicating that they are 
directories. The subdirectories themselves are 
files, linked through the FAT as usual. Their 
contents are identical in character to the 
contents of the root directory. 


Pre-2.1 programs that use system calls not 
described in this chapter will be unable to make 
use of files in other directories. Those files 
not necessary for the current task can be placed 
in other directories. 


L=LS 


Attributes, as described in the section on 
directories, apply to the tree-structured 
directories in the following manner: 


ATTRIBUTE MEANING/FUNCTION 


volume id Present at the root. Only one file 
may have this set. 


directory Indicates that the directory entry is 
itself a directory. Cannot be changed 
with 43H. 


read-only Meaningless for a directory. 


archive Meaningless for a directory. 
hidden/ Prevents directory entry from being 
system found. Function 3BH will still work. 


1.6 INTERRUPTS 


MS-DOS reserves interrupts 20H through 3FH for its 
own use. The table of interrupt routine addresses 
(vectors) is maintained in locations 80H-FCH. 
Table 1-3 lists the interrupts in numeric order; 
Table 1-4 lists the interrupts in alphabetic order 
(o£ the description). User programs should only 
issue Interrupts 20H, 21H, 25H, 26H, and 27H. 
(Function Requests 4CH and 31H are the preferred 
method for Interrupts 20H and 27H for versions of 
MS-DOS that are 2.0 and higher.) 


Note: Interrupts 22H, 23H, and 24H are not 
interrupts that can be issued by user programs; 
they are simply locations where a segment and 
offset address are stored. 
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Table 1-3: MS-DOS Interrupts, Numeric Order 


INTERRUPT 

HEX DEC DESCRIPTION 

20H 32 Program Terminate 

21H 33 Function Request 

22H 34 Terminate Address 

23H 35 <ALT-C> Exit Address 

24H 36 Fatal Error Abort Address 
25H 37 Absolute Disk Read 

26H 38 Absolute Disk Write 

27H 39 Terminate But Stay Resident 


28-40H 40-64 RESERVED -- DO NOT USE 


Table 1-4: MS-DOS Interrupts, Alphabetic Order 


INTERRUPT 

DESCRIPTION HEX DEC 
Absolute Disk Read 2H 37 
Absolute Disk Write 26H 38 
<ALT-C> Exit Address 23H 35 
Fatal Error Abort Address 24H 36 
Function Request 21H 33 
Program Terminate 20H 32 
RESERVED -~ DO NOT USE 28-40H 40-64 
Terminate Address 22H 34 
Terminate But Stay Resident 27H 39 
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Program Terminate (Interrupt 20H) 


Call 
cs 
Segment address of Program 
Segment Prefix 


Return 
None 


Interrupt 20H causes the current process to 
terminate and returns control to its parent 
process. All open file handles are closed and the 
disk cache is cleaned. This interrupt is almost 
always used in old .COM files for termination, 


The CS register must contain the segment address 
of the Program Segment Prefix before you call this 
interrupt. 


The following exit addresses are restored from 
the Program Segment Prefix: 


EXIT ADDRESS OFFSET 
Program Terminate OAH 
ALT-C OEH 
Critical Error 12H 


All file buffers are flushed to disk. 


Note: Close all files that have changed in Length 
before issuing this interrupt. If a changed file 
is not closed, its length is not recorded 
correctly in the directory. See Functions 10H and 
3EH for a description of the Close File system 
calls. 
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Interrupt 20H is provided for compatibility with 
versions of MS-DOS prior to 2.0. New programs 
should use Function Request 4CH, Terminate a 
Process. 


Macro Definition: terminate macro 
int 20H 
endm 


Example: 


;CS must be equal to PSP values given at program start 
*(ES and DS values) 

INT 20H 
‘There is no return from this interrupt 


Function Request (Interrupt 21H) 


Call 
AH 
Function number 
Other registers as specified 
in individual function 


Return 
As specified in individual function 


The AH register must contain the number of the 
system function. See Chapter 1.7, "Function 
Requests," for a description of the MS-DOS system 
functions. 


Note: No macro is defined for this interrupt, 
because all function descriptions in this chapter 
that define a macro include Interrupt 21H. 


Example: 
To call the Get Time function: 


mov ah,2CH ;Get Time is Function 2CH 
int 21H sTHIS INTERRUPT 


Interrupts 22H to 24H 


The following are not true interrupts, but rather 
storage locations for a segment and offset 
address. The interrupts are issued by MS-DOS 
under the specified circumstance. You can change 
any of these addresses with Function Request 25H 
(Set Vector) if you prefer to write your own 
interrupt handlers. 


Interrupt 22H — Terminate Address 


When a program terminates, control transfers to 
the address at offset OAH of the Program Segment 
Prefix. This address is copied into the Program 
Segment Prefix, from the Interrupt 22H vector, 
when the segment is created. 


Interrupt 23H —- ALT-C Exit Address 


If the user types ALT-C during keyboard input or 
display output, control transfers to the INT 23H 
vector in the interrupt table. This address is 
copied into the Program Segment Prefix, from the 
Interrupt 23H vector, when the segment is created. 


Tf£ the ALT-C routine preserves all registers, it 


can end with an IRET instruction (return from 
interrupt) to continue program execution. When 
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the interrupt occurs, all registers are set to the 
value they had when the original call to MS-DOS 
was made. There are no restrictions on what an 
ALT-C handler can do — including MS-DOS function 
calls — so long as the registers are unchanged if 
IRET is used. 


If Function 09H or OAH (Display String or Buffered 
Keyboard Input) is interrupted by ALT-C the three- 
byte sequence 03H-ODH-OAH (ETX-CR-LF) is sent to 
the display and the function resumes at the 
beginning of the next line. 


If the program creates a new segment and loads a 
second program that changes the ALT-C address, 
termination of the second program restores the 
ALT-C address to its value before execution of the 
second program. 


Interrupt 24H — Fatal Error Abort Address 


If a fatal disk error occurs during execution of 
one of the disk I/O function calls, control 
transfers to the INT 24H vector in the vector 
table. This address is copied into the Program 
Segment Prefix, from the Interrupt 24H vector, 
when the segment is created. 


BP:SI contains the address of a Device Header 
Control Block from which additional information 
can be retrieved. 


Note: Interrupt 24H is not issued if the failure 
occurs during execution of Interrupt 251 (Absolute 
Disk Read) or Interrupt 26H (Absolute Disk 
Write). These errors are usually handled by the 
MS-DOS error routine in COMMAND.COM that retries 
the disk operation, then gives the user the choice 
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of aborting, retrying the operation, or ignoring 
the error. The following topics give you the 
information you need about interpreting the error 
codes, managing the registers and stack, and 
controlling the system's response to the error in 
order to write your own error-handling routines. 


Error Codes 


When an error-handling program gains control from 
Interrupt 24H, the AX and DI registers can contain 
codes that describe the error. If Bit 7 of AH is 
1, the error is either a bad image of the File 
Allocation Table or an error occurred ona 
character device. The device header passed in 
BP:SI can be examined to determine which case 
exists. If the attribute byte high order bit 
indicates a block device, then the error was a bad 
FAT. Otherwise, the error is on a character 
device. 
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The following are error codes for Interrupt 24H: 


ERROR 
CODE 


AWPU OTD USP WNEH CO 


er =: DESCRIPTION 
Attempt to write on write-protected disk 
Unknown unit 

Drive not ready 

Unknown command 

Data error 

Bad request structure length 
Seek error 

Unknown media type 

Sector not found 

Printer out of paper 

Write fault 

Read fault 

General failure 
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The user stack will be in effect (the first item 
described here is at the top of the stack), and 
will contain the following from top to bottom: 


IP MS-DOS registers from 
cs issuing INT 24H 
FLAGS 


AX User registers at time of original 
BX INT 21H request 


IP From the original INT 21H 
cs from the user to MS-DOS 
FLAGS 


The registers are set such that if an IRET is 
executed, MS-DOS will respond according to (AL) as 
follows: 


(AL) =0 ignore the error 
=] retry the operation 
2 terminate the program via INT 23H 


= 
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Notes: 


1. 


Before giving this routine control for 
disk errors, MS-DOS performs five 
retries. 


For disk errors, this exit is taken only for 
errors occurring during an Interrupt 21H. It 
is not used for errors during Interrupts 251 
or 26H. 


This routine is entered in an interrupts- 
disabled state. 


The SS, SP, DS, ES, BX, CX, and DX registers 
must be preserved. 


This interrupt handler should refrain from 
using MS-DOS funtion calls. If necessary, it 
may use calls 01H through OCH. Use of any 
other call will destroy the MS-DOS stack and 
will leave MS-DOS in an unpredictable state. 


The interrupt handler must not change the 
contents of the device header. 


If the interrupt handler will handle errors 
rather than returning to MS-DOS, it should 
restore the application program's registers 
from the stack, remove all but the last three 
words on the stack, then issue an IRET. This 
will return to the program immediately after 
the INT 21H that experienced the error. Note 
that if this is done, MS-DOS will be in an 
unstable state until a function call higher 
than OCH is issued. 
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Absolute Disk Read (Interrupt 254) 


Call 
Al 

Drive number 
DS :BX 

Disk Transfer Address 
CX 

Number of sectors 
DX 

Beginning relative sector 
Return 
AL 

Error code if CF=1 
Flags 

CF if successful 


0 
1 if not successful 


The registers must contain the following: 


AL Drive number (0=A, 1=B, etc.). 

BX Offset of Disk Transfer Address 
(from segment address in DS). 

CX Number of sectors to read. 

DX Beginning relative sector. 


This interrupt transfers control to the MS-DOS 
BIOS. The number of sectors specified in CX is 
read from the disk to the Disk Transfer Address. 
Its requirements and processing are identical to 
Interrupt 26H, except data is read rather than 
written. 


Note: All registers except the segment registers 
are destroyed by this call. Be sure to save any 
registers your program uses before issuing the 
interrupt. 
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The system pushes the flags at the time of the 
call; they are still there upon return. (This is 
necessary because data is passed back in the 
flags.) Be sure to pop the stack upon return to 
prevent uncontrolled growth. 


If the disk operation was successful, the Carry 
Flag (CF) is 0. If the disk operation was not 
successful, CF is 1 and AL contains the MS-DOS 
error code (see Interrupt 24H earlier in this 
section for the codes and their meaning). 


Macro Definition: 
abs disk read macro disk,buffer,num sectors,start 


mov al,disk 

MOV bx,offset buffer 
Mov cx,;num_sectors 
Mov dh,start 

int 25 

endm 


See Absolute Disk Write in the next section for an 
example. 


Absolute Disk Write (Interrupt 268) 


Call 
AL n 
Drive number 
DS :BX 
Disk Transfer Address 
CX 
Number of sectors 
DX 
Beginning relative 
sector 
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Return 
AL 
Error code if CF = 1 
FLAGS 
CF = 0 if successful 
1 if not successful 


The registers must contain the following: 


AL Drive number (0=A, 1=B, etc.). 

BX Offset of Disk Transfer Address 
(from segment address in DS). 

CX Number of sectors to write. 

DX Beginning relative sector. 


This interrupt transfers control to the MS-DOS 
BIOS. The number of sectors specified in CX is 
written from the Disk Transfer Address to the 
disk. Its requirements and processing are 
identical to Interrupt 25H, except data is written 
to the disk rather than read from it. 


Note: All registers except the segment registers 
are destroyed by this call. Be sure to save any 
registers your program uses before issuing the 
interrupt. 


The system pushes the flags at the time of the 
call; they are still there upon return. (This is 
necessary because data is passed back in the 
flags.) Be sure to pop the stack upon return to 
prevent uncontrolled growth. 


If the disk operation was successful, the Carry 
Flag (CF) is 0. If the disk operation was not 
successful, CF is 1 and AL contains the MS~DOS 
error code (see Interrupt 24H for the codes and 
their meaning). 
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Macro Definition: 


abs disk write macro disk,buffer,num sectors,start 


mov al,disk 

Mov bx,offset buffer 
mov cx,num_sectors 
mov dh, start 

int 26H 

endm 


Example: 


The following program copies the contents of a 
single-sided disk in drive A: to the disk in 
drive B:, verifying each write. It uses a buffer 
of 32K bytes: 


off equ 0 
on equ il 
prompt "Source in A, target in B",13,10 


db 
db "Any key to start. $" 
start dw 0 

buffer db 64 dup (512 dup (?)) ;64 sectors 


int_26H: display prompt ;see Function 09H 


read_kbd ;see Function 08H 

verify on ;see Function 2EH 

mov cx,19 ;copy 19 groups of 
64 sectors 
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copy: push Cx ;save the loop counter 
abs disk read 0,buffer,64,start 
abs disk write 1,buffer,64,start 
add start,64 :do the next 64 sectors 


pop cx s;restore the loop 
counter 

loop copy 

verify off ;see Function 2EH 


Terminate But Stay Resident (Interrupt 27H) 


Call 

CS :DX 
First byte following 
last byte of code = 


Return 
None 


The Terminate But Stay Resident call is used to 
make a piece of code remain resident in the system 
after its termination. Typically, this call is 
used in .COM files to allow some device-specific 
interrupt handler to remain resident to process 
asynchronous interrupts. 


DX must contain the offset (from the segment 
address in CS) of the first byte following the 
last byte of code in the program. When Interrupt 
27H is executed, the program terminates but is 
treated as an extension of MS-DOS; it remains 
resident and is not overlaid by other programs 
when it terminates. 


This interrupt is provided for compatibility with 


versions of MS-DOS prior to 2.0. New programs 
should use Function 31H, Keep Process. 
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Macro Definition: stay resident macro last instruc 
mov dx,offset last instruc 


inc dx 
int 27H 
endm 


Example: 


:CS must be equal to PSP values given at program start 
*(ES and DS values) 

mov DX, LastAddress 

int 27H 
sThere is no return from this interrupt 


1.7 FUNCTION REQUESTS 


Most of the MS-DOS function calls require input to 
be passed to them in registers. After setting the 
proper register values, the function may be 
invoked in one of the following ways: 


1. Place the function number in AH and execute a 
long call to offset 50H in your Program 
Segment Prefix. Note that programs using this 
method will not operate correctly on versions 
of MS-DOS that are lower than 2.0. 


2. Place the function number in AH and issue 
Interrupt 21H. All of the examples in this 
chapter use this method. 


3. An additional method exists for programs that 
were written with different calling 
conventions. This method should be avoided 
for all new programs. See Chapter 1.7.1. 
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1.7.1 CP/M(R)-COMPATIBLE CALLING SEQUENCE 


A different sequence can be used for programs that 
must conform to CP/M calling conventions: 


1. Move any required data into the appropriate 
registers (just as in the standard sequence). 


2. Move the function number into the CL register. 


3. Execute an intrasegment call to location 5 in 
the current code segment. 


This method can only be used with functions 00H 
through 24H that do not pass a parameter in AL. 
Register AX is always destroyed when a function is 
called in this manner. 


1.7.2 TREATMENT OF REGISTERS 


When MS-DOS takes control after a function call, 
it switches to an internal stack. Registers not 
used to return information (except AX) are 
preserved. The calling program's stack must be 
large enough to accommodate the interrupt system 
—- at least 128 bytes in addition to other needs. 


1.7.3 FUNCTION REQUEST DESCRIPTIONS 


The macro definitions for MS-DOS system calls 00H 
through 2EH can be found in Chapter 1.8. 


Table 1-5 lists the function requests in numeric 
order; Table 1-6 lists the function requests in 
alphabetic order of the description. 


Table 1-5: MS-DOS Function Requests, Numeric 


Order 
FUNCTION 
NUMBER | FUNCTION NAME 
00H Terminate Program 
01H Read Keyboard and Echo 
02H Display Character 
03H Auxiliary Input 
04H Auxiliary Output 
OH Print Character 
06H Direct Console I/O 
07H Direct Console Input 


08H Read Keyboard 
09H Display String 


OAH Buffered Keyboard Input 

OBH Check Keyboard Status 

OCH Flush Buffer, Read Keyboard 
ODH Disk Reset 

OEFH Select Disk 


OFH Open File 
10H Close File 
11H Search for First Entry 


12H Search for Next Entry 
13H Delete File 

14H Sequential Read 

1a Sequential Write 

16H Create File 

17H Rename File 

19H Current Disk 

1AH Set Disk Transfer Address 
21H Random Read 

22H Random Write 

23H File Size 
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FUNCTION NAME 


Set Relative Record 

Set Vector 

Random Block Read 

Random Block Write 

Parse File Name 

Get Date 

Set Date 

Get Time 

Set Time 

Set/Reset Verify Flag 

Get Disk Transfer Address 
Get DOS Version Number 
Keep Process 

ALT-C Check 

Get Interrupt Vector 

Get Disk Free Space 
Return Country-Dependent Information 
Create Sub-Directory 
Remove a Directory Entry 
Change Current Directory 
Create a File 

Open a File 

Close a File Handle 

Read From File/Device 
Write to a File/Device 
Delete a Directory Entry 
Move a File Pointer 
Change Attributes 

I/O Control for Devices 
Duplicate a File Handle 
Force a Duplicate of a Handle 
Return Text of Current Directory 
Allocate Memory 
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NUMBER __ FUNCTION NAME 
49H Free Allocated Memory 
4AH Modify Allocated Memory Blocks 
4BH Load and Execute. a Program 
4CH Terminate a Process 
4DH Retrieve the Return Code of a Child 


4EH Find Match File 
4FH Step Through a Directory Matching Files 


54H Return Current Setting of Verify 
56H Move a Directory Entry 
57H Get/Set Date/Time of File 


Table 1-6: MS-DOS Function Requests, Alphabetic 


Order 
_ __ FUNCTION NAME NUMBER 
Allocate Memory 48H 
Auxiliary Input 03H 
Auxiliary Output 04H 
Buffered Keyboard Input OAH 
Change Attributes 43H 
Change the Current Directory 3BH 
Check Keyboard Status OBH 
Close a File Handle 3EH 
Close File 10H 
ALT-C Check 33H 
Create a File 3CH 
Create File 16H 
Create Sub-Directory 39H 
Current Disk 19H 
Delete a Directory Entry 41H 
Delete File 13H 
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FUNCTION NAME 


Direct Console Input 
Direct Console I/O 

Disk Reset 

Display Character 

Display String 

Duplicate a File Handle 
File Size 

Find Match File 

Flush Buffer, Read Keyboard 
Force a Duplicate of a Handle 
Free Allocated Memory 

Get Date 

Get Disk Free Space 

Get Disk Transfer Address 
Get DOS Version Number 

Get Interrupt Vector 

Get Time 

Get/Set Date/Time of File 
I/O Control for Devices 
Keep Process 

Load and Execute a Program 
Modify Allocated Memory Blocks 
Move a Directory Entry 
Move a File Pointer 

Open a File 

Open File 

Parse File Name 

Print Character 

Random Block Read 

Random Block Write 

Random Read 

Random Write 

Read From File/Device 

Read Keyboard 
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FUNCTION NAME 


Read Keyboard and Echo 

Remove a Directory Entry 

Rename File 

Retrieve the Return Code of a Child 
Return Current Setting of Verify 
Return Country—Dependent Information 
Return Text of Current Directory 
Search for First Entry 

Search for Next Entry 

Select Disk 

Sequential Read 

Sequential Write 

Set Date 

Set Disk Transfer Address 

Set Relative Record 

Set Time 

Set Vector 

Set/Reset Verify Flag 

Step Through a Directory Matching 
Terminate a Process 

Terminate Program 

Write to a File/Device 


Terminate Program (Function 00H) 


Call 

AH = 00H 

CS 
Segment address of 
Program Segment Prefix 


Return 
None 
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Function 00H is called by Interrupt 20H; it 
performs the same processing. 


The CS register must contain the segment address 
of the Program Segment Prefix before you call this 
interrupt. 


The following exit addresses are restored from the 
specified offsets in the Program Segment Prefix: 


Program terminate OAH 
ALT-C OEH 
Critical error 12H 


All file buffers are flushed to disk. 


Warning: Close all files that have changed in 
length before calling this function. If a changed 
file is not closed, its length is not recorded 
correctly in the directory. See Function 10H for 
a description of the Close File system call. 


Macro Definition: terminate program macro 


XOLK ah,ah 
int 21H 
endm 


Example: 


:CS must be equal to PSP values given at program 
start 
3(ES and DS values) 
mov ah,0 
int 21H 
;There are no returns from this interrupt 
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Read Keyboard and Echo (Function 01H) 


Call 
AH = 01H 


Return 
AL 
Character typed 


Function 01H waits for a character to be typed at 
the keyboard, then echos the character to the 
display and returns it in AL. If the character is 
ALT-C, Interrupt is executed. 


Macro Definition: read_kbd and echo macro 


mov ah, O1H 
int 21H 
endm 


Example: 


The following program both displays and prints 
characters as they are typed. If Return is 
pressed, the program sends Line Feed/Carriage 
Return to both the display and the printer: 


func 01H: read _kbd_and_echo ;THIS FUNCTION 
~ print char al s;see Function 
7050 
cmp al ,0DH ;is it a CR? 
jne func 01H j;no, print it 
print_char 10 ssee Function 
705 
display char 10 ;see Function 
:02H 
jmp func_01H ;get another 
scharacter 
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Display Character (Function 02H) 


Call 
AH = 02H 
DL 


Character to be displayed 


Return 
None 


Function 02H displays the character in DL. If 
ALT-C is typed, Interrupt 23H is issued. 


Macro Definition: display char macro character 


Example: 


mov d1,character 


mov ah ,02H 
int 21H 
endm 


The following program converts lowercase 
characters to uppercase before displaying them: 


func_02H: read_kbd 


cmp al,"a" 
j1 uppercase 
cmp al,“z" 
j9 uppercase 


sub al, 20H 


uppercase: display char al 
jmp func_02H: 
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ssee Function 08H 
sdon't convert 


sdon't convert 
sconvert to ASCII 
;code for uppercase 
;THIS FUNCTION 

get another 
character 


Auxiliary Input (Function 03H) 


Call 
AH = 03H 


Return 
AL 
Character from auxiliary device 


Function 03H waits for a character from the 
auxiliary input device (AUXIN), then returns the 
character in AL. This system call does not return 
a status or error code. 


If an ALT-C has been typed at console input, 
Interrupt 23H is issued. 


Macro Definition: aux_input macro 


mov ah,03H 
int 21H 
endm 


Example: 


The following program prints characters as they 
are received from the auxiliary device. It stops 
printing when an end-of-file character (ASCII 26, 
or ALT-Z) is received: 


func_03H: aux_input :THIS FUNCTION 
cmp al,lAH send of file? 
je continue syes, all done 


print_char al ssee Function 03 
jmp func_03H ;get another character 
continue: . 
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Auxiliary Output (Function 048) 


Call 
AH = 04H 
DL 
Character for auxiliary device 


Return 
None 


Function 04H sends the character in DL to the 
auxiliary output (AUXOUT) device. This system 
call does not return a status or error code. 


If a ALT-C has been typed at console input, 
Interrupt 23H is issued. 


Macro Definition: aux_output macro. character 
mov di,character 


mov ah,04H 
int 21H 
endm 
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Example: 


The following program gets a series of strings of 
up to 80 bytes from the keyboard, sending each to 
the auxiliary device. It stops when a null string 
(CR:only) is typed: 


string db 81 dup(?) ;see Function OAH 


func_O04H:get_string 80,string ;see Function OAH 
cmp string[1],0 snull string? 
je continue yes, all done 


XOK CX, CX 
mov cl, byte ptr string[1] ;get string length 


mov bx,0 ;set index to 0 
send it: aux output string[bx+2] ;THIS FUNCTION 
~ inc bx ;bump index 
loop send_it ssend another character 
jmp func_04H get another string 


continue: . 


Print Character (Function 05H) 


Call 
AH = 01 
DL 
Character for printer 


Return 
None 


Function 05 prints the character in DL on the 


standard printer device. If ALT-C has been typed 
at console input, Interrupt 23H is issued. 
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Macro Definition: 


Bxample: 


print char macro character 


mov dl,character 
mov ah,0H 
int 21H 


endm Da 


The following program prints a walking test 
pattern on the printer. 


pressed. 


line_num 


func_05H: 
start line: 


print_it: 


no_reset: 


db 0 

mov cx,60 
mov b1,33 
add bl1,line_num 
push cx 

mov cx,80 
print char bl 
inc bl 

cmp bl1,126 
jl no_reset 
mov b1,33 
loop print it 


print char 13 
print char 10 


inc 


pop 
loop 


Line_num 
cx 
start line; 


It stops if ALT-C is 


sprint 60 lines 

:first printable ASCII 
s;character (!) 

zto offset one character 
;save number-—of-lines counter 
;loop counter for line 

;THIS FUNCTION 

;move to next ASCII character 
;last printable ASCII 
;character (~) 

snot there yet 

sstart over with (!) 


yprint another character 
;Ccarriage return 

sline feed 

;to offset lst char. of line 
;restore #~of-lines counter 
print another line 
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Direct Console I/O (Function O6H) 


Call 
AH = 06H 
DL 
FFH = Check for keyboard 
input. 
Otherwise = display DC on 
screen. 


Return 

AL 
If DL = FFH (255) before call, 
then Zero flag set means AL has 
character from keyboard. 
Zero flag not set means there was 
not a character to get, and AL = 0 


The processing depends on the value in DL when the 
function is called: 


DL is FFH (255) -- If a character has been 
typed at the keyboard, it is returned in AL 
and the Zero flag is 0; if a character has 
not been typed, the Zero flag is l. 


DL is not FFH — The character in DL is 
displayed. 


This function does not check for ALT-C. 


Macro Definition: dir _console io macro switch 
mov dl,switch 


mov ah,06H 
int 21H 
endm 


1-45 


Example: 


The following program sets the system clock to 0 
and continuously displays the time. When any 
character is typed, the display stops changing; 
when any character is typed again, the clock is 
reset to 0 and the display starts again: 


time db "00:00:00.00",13,10,"$" ;see Function 09H 

: ;for explanation of $ 

ten db 10 

func 06H: set time 0,0,0,0 ;see Function 2DH 

read clock: get_time ;see Function 2CH 
convert ch,ten,time ;see end of chapter 


convert cl,ten,time[3] ;see end of chapter 
convert dh,ten,time[6] ;see end of chapter 
convert dl,ten,time[9] ;see end of chapter 


display time ;see Function 09H 
dir_console_io FFH ;THIS FUNCTION 
jne stop yyes, stop timer 
jmp read_ clock sno, keep timer 
;running 
stop: read_kbd° ;see Function 08H 
jmp func_06H Start over 


Direct Console Input (Function 07H) 


Call 
AH = 07H 


Return 
AL 
Character from keyboard 


Function 07H waits for a character to be typed, 
then returns it in AL. This function does not 
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echo the character or check for ALT-C. (For a 
keyboard input function that echoes or checks for 
ALT-C, see Functions 01H or 08H.) 


Macro Definition: dir _console input macro 


Example: 


mov ah,07H 
int 21H 
endm 


The following program prompts for a password (8 
characters maximum) and places the characters into 
a string without echoing them: 


password db 8 dup(?) 
prompt db "Password: $" 


func_07H: display prompt 
mov cx,8 
xor bx,bx 
get_pass: dir console _input 
cmp al,O0DH 
je continue 
mov password [bx] ,al 
inc bx 
loop get_pass 
continue: . 


3see Function 09H for 
explanation of $ 


ssee Function 098 

maximum length of password 
:sO BL can be used as index 
;THIS FUNCTION 

twas it a CR? 

zyes, all done 

no, put character in string 
zbump index 

get another character 

3;BX has length of password+l 
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Read Keyboard (Function 08H) 


Call 
AH = 08H 


Return 
AL 
Character from keyboard 


Function 08H waits for a character to be typed, 
then returns it in AL. If ALT-C is pressed, 
Interrupt 23H is executed. This function does not 
echo the character. (For a keyboard input 
function that echoes the character or checks for 
ALT-C, see Function 01H.) 


Macro Definition: read kbd macro 


mov ah,08H 
int 21H 
endm 


Example: 


The following program prompts for a password (8 
characters maximum) and places the characters into 
a string without echoing them: 


password db 8 dup(?) 
prompt db “Password: $" ssee Function 09H 
for explanation of $ 


func_08H: display prompt 3;see Function 09H 
mov cx,8 ;maximum length of password 
xor bx,bx ;BL can be an index 
get_pass: read _kbd ;THIS FUNCTION 
cmp al,0DH zwas it a CR? 
je continue yes, all done 
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mov password[bx],al ;no, put char. in string 


inc bx bump index 
loop get_pass get another character 


continue: . BX has length of passwordt+tl 


Display String (Function 09H) 


Call 
AH = 09H 
DS :DX 
String to be displayed 


Return 
None 


DX must contain the offset (from the segment 
address in DS) of a string that ends with "S$". 
The string is displayed (the $ is not displayed). 


Macro Definition: display macro string 
lea dx,string 


mov ah,09H 
int 21H 
endm 
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Exauple: 


The following program displays the hexadecimal 
code of the key that is typed: 


table db "0123456789ABCDEF" 

sixteen db 16 

result db " — 00OH",13,10,"S" ;see text for 
;explanation of $ 


func _09H:read_kbd_and_echo ;see Function 01H 
convert al,sixteen,result[3] ;see end of chapter 
display result ;THIS FUNCTION 
jmp func 09H 7do it again 


Buffered Keyboard Input. (Function OAH) 


Call 
AH = OAH 
DS :DX 
Input buffer 


Return 
None 


DX must contain the offset (from the segment 
address in DS) of an input buffer of the following 
form: 


BYTE 7 CONTENTS 

1 Maximum number of characters in buffer, 
including the CR (you must set this value). 

2 Actual number of characters typed, not 
counting the CR (the function sets this 
value). 


3-n Buffer; must be at least as long as the 
number in byte l. 


This function waits for characters to be typed. 
Characters are read from the keyboard and placed 
in the buffer beginning at the third byte until 
Return is typed. If the buffer fills to one less 
than the maximum, additional characters typed are 
ignored and ASCII 7 (BEL) is sent to the display 
until Return is pressed. The string can be edited 
as it is being entered. If ALT-C is typed, 
Interrupt 23H is issued. 


The second byte of the buffer is set to the number 
of characters entered (not counting the CR). 


Macro Definition: get string macro limit,string 


lea dx, string 
mov string, limit 
mov ah, 0AH 

int 21H 

endm 


Example: 


The following program gets a 16-byte (maximum) 
string from the keyboard and fills a 24-line by 
80-character screen with it: 


buffer _. 
max_length 
chars_entered 
string 
strings per line 


erlf 


func_OAH: 


display screen: 


display_line: 


label 


db 
db 
db 
dw 


db 


byte 

? 

? 

17 dup (?) 
0 


13,10,"$" 


get_string 17,buffer 


XOr 


push 
mov 


bx , bx 


bl,chars entered 
buffer [bx+2],"$" 
al,80 


chars_entered 


ah,ah 

strings per_line,ax 
Cx, 24 

cx 
ex,strings per line 


display string 


Loop 


display line 


display crif 


Pop 
loop 


cx 
display screen 


maximum length 
ynumber of chars. 
316 chars + CR 
show many strings 
;fit on line 


;THIS FUNCTION 
;so byte can be 
sused as index 
get string length 
ssee Function 09H 
;columns per line 


;times string fits 
on line 

yclear remainder 
;save col. counter 
row counter 

ysave it 

sget col. counter 
;see Function 09H 


7see Function 09H 
get line counter 


;display 1 more line 


Check Keyboard Status (Function OBH) 


Call 

AH = OBH 

Return 

AL 
255 (FFH) = characters in type-ahead 
buffer 
0 = no characters in type-ahead 


buffer 


Checks whether there are characters in the type- 
ahead buffer. If so, AL returns FFH (255); if 
not, AL returns 0. If ALT-C is in the buffer, 
Interrupt 23H is executed. 


Macro Definition: check_kbd status macro 


mov ah, OBH 
int 21H 
endm 
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Example: 


The following program continuously displays the 


time until any key is pressed. 


time db "00:00:00.00",13,10,"5" 

ten db 10 

Func OBH: get_time ;see Function 2CH 
convert ch,ten, time ;see end of chapter 


convert cl,ten,time[3] ;see 
convert dh,ten,time[6] ;see 
convert dl,ten,time[9] ;see 


end of chapter 
end of chapter 
end of chapter 


display time ;see Function 09H 

check _kbd_status ;THIS FUNCTION 

cmp al, FFH ;has a key been typed? 

je all done syes, go home 

jmp func_OBH ;no, keep displaying 
:time 


Flush Buffer, Read Keyboard (Function 0CH) 


Cal 


= OCH 


Bi 


1, 6, 7, 8, or OAH = The 
corresponding function 
is called. 

Any other value = no 
further processing. 


Return 

AL 
0 = Type-ahead buffer was 
flushed; no other 
processing performed. 


The keyboard type-ahead buffer is emptied. 
Further processing depends on the value in AL when 
the function is called: 


1, 6, 7, 8, or OAH -—- The corresponding MS-DOS 
function is executed. 


Any other value — No further processing; AL 
returns 0. 


Macro Definition: flush_and_read_kbd macro switch 
mov al,switch 


mov  ah,0CH 
int 21H 
endm 


Example: 


The following program both displays and prints 
characters as they are typed. If Return is 
pressed, the program sends carriage return/line 
feed to both the display and the printer. 


func_OCH: flush_and_read_ kbd 1 ;THIS FUNCTION 


print_char al ;see Function 05H 

cmp al,ODH sis it a CR? 

jne func_OCH ;no, print it 
print_char 10 ;see Function 05 
display char 10 7see Function 02H 

jmp func_OCH ;get another character 
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Disk Reset (Function ODH) 


Call 
AH = ODH 


Return 
None 


Function ODH is used to ensure that the internal 
buffer cache matches the disks in the drives. 

This function writes out dirty buffers (buffers 
that have been modified), and marks all buffers in 
the internal cache as free. 


Function ODH flushes all file buffers. It does 
not update directory entries; you must close files 
that have changed to update their directory 
entries (see Function 10H, Close File). This 
function need not be called before a disk change 
if all files that changed were closed. It is 
generally used to force a known state of the 
system; ALT-C interrupt handlers should call this 
function. 


Macro Definition: disk reset macro disk 


mov ah,0DH 
int 21H 
endm 
Example: 
mov ah, ODH 
int 21H 


*There are no errors returned by this call. 


Select Disk (Function OEH) 


Call 
AH = OFH 
DL 
Drive number 


(0 =A:, 1=B:, etc.) 


Return 
AL 


Number of logical drives 


The drive specified in DL 


(0 = A:, 1 = Bs, etc.) 


is selected as the default disk. The number of 


drives is returned in AL. 


Macro Definition: select disk macro disk 


Example: 


mov dl1,disk[-64] 


mov ah,0OEH 
int 21H 
endm 


The following program selects the drive not 
currently selected in a 2-drive system: 


func_OEFH: current disk 


cmp al,00H 

je select_b 

select _disk "A" 
continue 


select_b: select disk "B" 
continue: . 


ssee Function 19H 
;drive A: selected? 
yes, select B 
;THIS FUNCTION 


;THIS FUNCTION 
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Open File (Function OFH) 


Call 

AH = OFH 

DS :DX 
Unopened FCB 


Return 
AL 
0 = Directory entry found 
255 (FFH) = No directory entry found 


DX must contain the offset (from the segment 
address in DS) of an unopened File Control Block 
(FCB). The disk directory is searched for the 
named file. 


If a directory entry for the file is found, AL 
returns 0 and the FCB is filled as follows: 


If the drive code was 0 (default disk), it is 
changed to the actual disk used (1 = A:, 2 =B:, 
etc.). This lets you change the default disk 
without interfering with subsequent operations on 
this file. 


The Current Block field (offset OCH) is set 
to zero. 


The Record Size (offset OFH) is set to the 
system default of 128. 


The File Size (offset 10H), Date of Last 
Write (offset 14H), and Time of Last Write 
(offset 16H) are set from the directory 
entry. 


Before performing a sequential disk operation on 
the file, you must set the Current Record field 
(offset 20H). Before performing a random disk 
operation on the file, you must set the Relative 
Record field (offset 21H). If the default record 
size (128 bytes) is not correct, set it to the 
correct length. 


If a directory entry for the file is not found, AL 
returns FFH (255). 


Macro Definition: open macro fcb 
mov dx,offset fcb 


mov ah,0FH 
int 21H 
endm 


Example: 


The following program prints the file named 
TEXTFILE.ASC that is on the disk in drive B:. If 
a partial record is in the buffer at end-of-file, 
the routine that prints the partial record prints 
characters until it encounters an end-of-file mark 
(ASCII 26, or ALT-Z): 


fcb db 2,"TEXTFILEASC" 
db 25 dup (?) 

buffer db 128 dup (?) 

func_OFH: set dta buffer ;Ssee Function 1AH 
open fcb ;THIS FUNCTION 

read_ line: read seq fcb ;see Function 14H 
cmp al,02H send of file? 
je all_done ryes, go home 
cmp al,00H ;more to come? 


j9 check_more 


mov cx,128 
xor si,si 
print it: print char buffer [si] 
inc si 
loop print_it 
jmp = read_line 
check_more: cmp al,03H 
jne all done 
mov cx, 128 
xor si,Si 
find eof: cmp buffer([si] ,26 
je all_done 
print_char buffer [si] 
inc si 


loop find_eof 
all_done: close fcb 


Close File (Function 10H) 


Call 

AH = 10H 

DS :DX 
Opened FCB 


Return 
AL 


sno, check for partial 
yrecord ; 
yes, print the buffer 
:set index to 0 

;see Function 054 
;bump index 

print next character 
;read another record 
;part. record to print? 
sno 

zyes, print it 

;set index to 0 
;end-of-file mark? 
ryes 

3;see Function 058 
s;bump index to next 
;character 


:see Function 10H 


0 = Directory entry found 
FFH (255) = No directory entry found 


DX must contain the offset (to the segment address 
in DS) of an opened FCB. The disk directory is 
searched for the file named in the FCB. This 
function must be called after a file is changed to 


update the directory entry. 
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If a directory entry for the file is found, the 
location of the file is compared with the 
corresponding entries in the FCB. The directory 
entry is updated, if necessary, to match the FCB, 
and AL returns 0. 


If a directory entry for the file is not found, AL 
returns FFH (255). 


Macro Definition: close macro fcb 
mov dx,offset fcb 
MOV ah, 10H 
int 21H 
endm 


Example: 


The following program checks the first byte of the 
file named MOD1.BAS in drive B: to see if it is 
FFH, and prints a message if it is: 


message db "Not saved in ASCII format",13,10,"5" 
fcb db 2,"MOD1L BAS" 

db 25 dup (?) 
buffer db 128 dup (7?) 


func_10H: set dta buffer ;see Function 1AH 
y open fcb ;see Function OFH 
read seq fcb ;see Function 14H 
cmp  buffer,FFH ;is first byte FFH? 
jne all done = j;no 
display message ;see Function 09H 
all_ done: close fcb ;THIS FUNCTION 


Search for First Entry (Function 11H) 


Call 

AH = 11H 

DS :DX 
Unopened FCB 


Return . : 
0 = Directory entry found 
FFH (255) = No directory entry found 


DX must contain the offset (from the segment 
address in DS) of an unopened FCB. The disk 
directory is searched for the first matching name. 
The name can have the ? wild card character to 
match any character. To search for hidden or 
system files, DX must point to the first byte of 
the extended FCB prefix. 


If a directory entry for the filename in the FCB 

is found, AL returns 0 and an unopened FCB of the 
same type (normal or extended) is created at the 

Disk Transfer Address. 


If a directory entry for the filename in the FCB 
is not found, AL returns FFH (255). 
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Notes: 


If an extended FCB is used, the following search 
pattern is used: 


1. If the FCB attribute is zero, only normal file 
entries are found. Entries for volume label, 
sub-directories, hidden, and system files will 
not be returned, 


2. If the attribute field is set for hidden or 
system files, or directory entries, it is to 
be considered as an inclusive search. All 
normal file entries plus all entries matching 
the specified attributes are returned. To 
look at all directory entries except the 
volume label, the attribute byte may be set to 
hidden + system + directory (all 3 bits on). 


3. If the attribute field is set for the volume 
label, it is considered an exclusive search, 
and only the volume label entry is returned. 


Macro Definition: search first macro fcb 
mov dx,offset fcb 


mov ah,llH 
int 21H 
endm 


Example: 


The following program verifies the existence of a 
file named REPORT.ASM on the disk in drive B:: 


yes db . "FILE EXISTS.$" 
no db "FILE DOES NOT EXIST.$" 
fcb dip 2,"REPORT ASM" 


db 25 dup (?) 
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buffer db 128 dup (?) 


func _llH: set_dta buffer ;see Function 1AH 
search first fcb ?THIS FUNCTION 
cmp  al,FFH ;directory entry found? 
je not there ;no 
display yes ;see Function 09H 
jmp continue 

not_there: display no ssee Function 09H 


continue: display crlf ;see Function 09H 


Search for Next Entry (Function 128) 


Call 

AH = 12H 

DS :DX 
Unopened FCB 


Return 
AL 
0 = Directory entry found 
FFH (255) = No directory entry found 


DX must contain the offset (from the segment 
address in DS) of an FCB previously specified ina 
call to Function 11H. Function 12H is used after 
Function 11H (Search for First Entry) to find 
additional directory entries that match a filename 
that contains wild card characters. The disk 
directory is searched for the next matching name. 
The name can have the ? wild card character to 
match any character. To search for hidden or 
system files, DX must point to the first byte of 
the extended FCB prefix. 
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If a directory entry for the filename in the FCB 
is found, AL returns 0 and an unopened FCB of the 
same type (normal or extended) is created at the 
Disk Transfer Address. 


If a directory entry for the filename in the FCB 
is not found, AL returns FFH (255). 


Macro Definition: search next macro fcb 


Example: 


mov dx,offset fcb 
mov ah,12H 

int 21H 

endm 


The following program displays the number of files 
on the disk in drive B: 


message 
files 
ten 

fcb 


buffer 


func_12H: 


search dir: 


db 
db 
db 
db 
db 
db 


"No files",10,13,"5" 
0 

10 

29 222 PPP 22222" 

25 dup (?) 

128 dup (?) 


set_dta buffer 
search first fcb 
cmp al,FFH 


je 


all_done 


inc files 


search next fcb 
cmp al,FFH 


je 


done 


inc files 
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3see Function 14H 
ssee Function 11H 


directory entry found? 


mno, no files on disk 
7yes, increment file 
;counter 

;THIS FUNCTION 
;directory entry found? 
no 

ryes, increment file 
;counter 


jmp search dir check again 
done: convert files,ten,message ;see end of chapter 
all done: display message ;see Function 09H 


Delete File (Function 13H) 


Call 
AH = 13H 
DS :DX 
Unopened FCB 


Return 
0 = Directory entry found 
FFH (255) = No directory entry found 


DX must contain the offset (from the segment 
address in DS) of an unopened FCB. The directory 
is searched for a matching filename. The filename 
in the FCB can contain the ? wild card character 
to match any character. 


If a matching directory entry is found, it is 
deleted from the directory. If the ? wild card 
character is used in the filename, all matching 
directory entries are deleted. AL returns 0. 


If no matching directory entry is found, AL 
returns FFH (255). 


Macro Definition: delete macro fcb 
mov dx,offset fcb 


mov ah, 13H 
int 21H 
endm 
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Example: 


The following program deletes files on the disk in 
drive B: last written before December 31, 1982: 


year dw 1982 
month db 12 
day db 31 
files db 0 
ten db 10 


message db "NO FILES DELETED.",13,10,"$" 
;see Function 09H for 
;explanation of $ 

db =—s- 2, ""222?2?????7 

db 25 dup (?) 

buffer db 128 dup (?) 


fcb 


func_13H: set_dta buffer ;see Function JAH 
7 search first fcb ;see Function 11H 
cmp al,FFH ;directory entry found? 
je all_done ;no, no more files on disk 
compare: convert date buffer ;see end or chapter 
cmp cx,year ynext several lines 
jg next ;check date in directory 
emp dl,month yentry against date 
jg next yabove & check next file 
‘cmp dh,day ;if date in directory 
jge next fentry isn't earlier. 
delete buffer ;THIS FUNCTION 
inc files ;bump deleted-files counter 
next: search next fcb ;see Function 12H 
cmp al,00H directory entry found? 
je compare syes, check date 
cmp files,0 yany files deleted? 
je  all_done ;no, display NO FILES 
message. 
convert files, ten,message ;see end of chapter 
all done: display message ;see Function 09H 
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Sequential Read (Function 148) 


Read completed successfully 
EOF 

DIA too small 

EOF, partial record 


DX must contain the offset (from the segment 
address in DS) of an opened FCB. The record 
pointed to by the current block (offset OCH) and 
Current Record (offset 20H) fields is loaded at 
the Disk Transfer Address, then the Current Block 
and Current Record fields are incremented. 


The record size is set to the value at offset OEH 
in the FCB. AL returns a code that describes the 


processing: 
CODE MEANING 

0 Read completed successfully. 

1 End-of-file, no data in the record. 

2 Not enough room at the Disk Transfer Address 
to read one record without exceeding the 
segment's boundaries; read canceled. 

3 End-of-file; a partial record was read and 


padded to the record length with zeros. 
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Macro Definition: read seq macro fcb 
mov dx,offset fcb 


mov ah, 14H 
int 21H 
endm 


Example: 


The following program displays the file named 
TEXTFILE.ASC that is on the disk in drive B:; its 
function is similar to the MS-DOS TYPE command. 

If a partial record is in the buffer at end of 
file, the routine that displays the partial record 
displays characters until it encounters an end-of- 
file mark (ASCII 26, or ALT-Z): 


fcb db 2,"TEXTFILEASC" 
db 25 dup (?) 
buffer db 128 dup (?),"S" 
Func_ 14H: set_dta buffer ;see Function 1AH 
open fcb see Function OFH 
read _ line: read seq fc ;THIS FUNCTION 
cmp al1,02H :end-of-file? 
je all_done 7yes 
cmp al,02H yend-of-file with partial 
srecord? 
jg check more 7yes 
display buffer ssee Function 09H 
jmp read line ;get another record 
check more: cmp a1,03H ;partial record in buffer? 
~ jne all_done ;no, go home 
xor si,si ;set index to 0 
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find_eof: cmp buffer[si],26 ;is character EOF? 


je all _done 7yeS, no more to display 
display char buffer[{si] see Function 02H 
inc si ;bump index to next 
;Character 
jmp = Find eof 7Ccheck next character 
all done: close fcb ;see Function 10H 


Sequential Write (Function 15H) 


Call 

AH = 19 

DS :DX 
Opened FCB 


Return 


Write completed successfully 
Disk full 
02H = DIA too small 


o 

Sc 

aa 
"oll 


DX must contain the offset (from the segment 
address in DS) of an opened FCB. The record 
pointed to by Current Block (offset OCH) and 
Current Record (offset 20H) fields is written from 
the Disk Transfer Address, then the current block 
and current record fields are incremented. 


The record size is set to the value at offset OEH 
in the FCB. I£ the Record Size is less than a 
sector, the data at the Disk Transfer Address is 
written to a buffer; the buffer is written to disk 
when it contains a full sector of data, or the 
file is closed, or a Reset Disk system call 
(Function ODH) is issued. 
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AL returns a code that describes the processing: 


CODE _ ____ MEANING 


0 Transfer completed successfully. 
1 Disk full; write canceled. 


2 Not enough room at the Disk Transfer 
Address to write one record without 
exceeding the segment's boundaries; write 
canceled. 


Macro Definition: write seq macro fcb 
mov dx,offset fcb 


mov ah,1H 
int 21H 
endm 


See Create File (next function) for an example. 


Create File (Function 148) 


Call 

AH = 16H 

DS :DX 
Unopened FCB 


Return 
AL 
00H = Empty directory found 
FFH (255) = No empty directory 
available 


DX must contain the offset (from the segment 
address in DS) of an unopened FCB. The directory 
is searched for an empty entry or an existing 
entry for the specified filename. 


de7 


If an empty directory entry is found, it is 
initialized to a zero-length file, the Open File 
system call (Function OFH) is called, and AL 
returns 0. You can create a hidden file by using 
an extended FCB with the attribute byte (offset 
FCB-1) set to 2. 


If an entry is found for the specified filename, 
all data in the file is released, making a zero- 
length file, and the Open File system call 
(Function OFH) is issued for the filename (in 
other words, if you try to create a file that 
already exists, the existing file is erased, and a 
new, empty file is created). 


If an empty directory entry is not found and there 
is no entry for the specified filename, AL returns 
FFH (255). 


Macro Definition: create macro fcb 
mov dx,offset fcb 


mov ah,16H 
int 21H : 
endm: 


Example: 

The following program creates a file named DIR. TMP 

on the disk in drive B: that contains the disk 

number (1 = A:, 2 =B:, etc.) and filename from 

each directory entry on the disk: 

record size equ 14 ;0ffset of Record Size 
sfield of FCB 


fcbl db 2,"DIR TMP" 
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db 25. dup (?) 


fcb2 db 2222222? 22?22" 
db 25 dup (?) 

buffer db 128 dup (?) 

func_] 6H: set_dta buffer ;see Function 1AH 
search first fcb2 ;see Function 11H 
cmp al,FFH ;directory entry found? 
je all done ;no, no files on disk 
create fcbl ;THIS FUNCTION 
mov fcbl[record size] ,12 


write it: write seq fcbl 
search next fcb2 


cmp al,FFH 

je all _done 

jmp write it 
all done: close Ecbl 


Rename File (Function 17H) 


Call 

AH = 17H 

DS :DX 
Modified FCB 


Return 
AL 


;set record size to 12 
;see Function 15 

;see Function 12H 
;directory entry found? 
7no, go home 

yes, write the record 
7;see Function 10H 


OOH = Directory entry found 
FFH (255) = No directory entry 
found or destination already 


exists 
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DX must contain the offset (from the segment 
address in DS) of an FCB with the drive number and 
filename filled in, followed by a second filename 
at offset 11H. The disk directory is searched for 
an entry that matches the first filename, which 
can contain the ? wild card character. 


If a matching directory entry is found, the 
filename in the directory entry is changed to 
Match the second filename in the modified FCB (the 
two filenames cannot be the same name). If the ? 
wild card character is used in the second 
filename, the corresponding characters in the 
filename of the directory entry are not changed. 
AL returns 0. 


If a matching directory entry is found, the 
filename in the directory entry is changed to 
match the second filename in the modified FCB 
(the two filenames cannot be the same name). If 
the ? wild card character is use in the second 
filename, the corresponding characters in the 
filename of the directory entry are not changed. 
AL returns 0. 


Macro Definition: rename macro fcb,newname 
mov dx,offset ficb 


mov ah,17H 
int 21H 
endm 
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Example: 


The following program prompts for the name of a 
file and a new name, then renames the file: 


fcb 
promptl 
prompt2 
reply 
erlf 


func_17H: 


db 37 dup (?) 
db "Filename: $" 
db “New name: $" 
db 17 dup(?) 
db 13,10,"$" 


display promptl ;see Function 
get_string 15,reply ;see Function 
display crlf ;see Function 
parse reply[{2],fcb ;see Function 
display prompt2 ;see Function 
get_string 15,reply ;see Function 
display crlf :see Function 
parse reply [2] ,£cb[16] 

:see Function 
rename fcb ;THIS FUNCTION 


Current Disk (Function 19H) 


Call 
AH = 


19H 


Return 


AL 


Currently selected drive 
(0 = A, 1 = B, etc.) 


09H 
OAH 
09H 
29H 
09H 
OAH 
09H 


29H 


AL returns the currently selected drive (0 = A:, 
1 =B:, etc.). 
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Macro Definition: current disk macro 
mov ah,19H 
int 21H 
endm 


Example: 


The following program displays the currently 
selected (default) drive in a 2-drive system: 


message db "Current disk is $" ;see Function 09H 
;for explanation of $ 


erlf db 13,10,"S" 

func_19H: display message ;see Function 09H 
current disk ;THIS FUNCTION 
cmp al,00H vis it disk A? 
jne disk b sno, it's disk B: 
display char "A" ;see Function 02H 
jmp all_done 

disk _b: display char "B" ;see Function 02H 

all done: display crif see Function 09H 


Set Disk Transfer Address (Function JAH) 


Call 
AH = JAH 
DS :DX 
Disk Transfer Address 


Return 
None 


DX must contain the offset (from the segment 
address in DS) of the Disk Transfer Address. Disk 
transfers can neither wrap around from the end of 
the segment to the beginning nor overflow into 
another segment. 


Note: If you do not set the Disk Transfer 
Address, MS-DOS defaults to offset 80H in the 
Program Segment Prefix. 


Macro Definition: set dta macro buffer 
mov dx,offset buffer 


mov ah, 1AH 
int 21H 
endm 


See Random Read (next function) for an example. 


Random Read (Function 218) 


Call 
AH = 21H 
DS :DX 
Opened FCB 
Return 
OOH = Read completed successfully 
01H = EOF 
02H = DIA too small 
03H = EOF, partial record 
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DX must contain the offset (from the segment 
address in DS) of an opened FCB. The Current 
Block (offset OCH) and Current Record (offset 20H) 
fields are set to agree with the Relative Record 
field (offset 21H), then the record addressed by 
these fields is loaded at the Disk Transfer 
Address. 


AL returns a code that describes the processing: 


CODE 


0 


MEANING 
Read completed successfully. 
End-of-file; no data in the record. 


Not enough room at the Disk Transfer Address 
to read one record; read canceled. 


End-of-file; a partial record was read and 
padded to the record length with zeros. 


Macro Definition: read_ran macro fcb 


mov dx,offset fcb 


mov ah, 21H 
int 21H 
endm 


1-78 


Example: 


The following program prompts for a letter, 
converts the letter to its alphabetic sequence 
(A= 1, B = 2, etc.), then reads and displays the 
corresponding record froma file named 
ALPHABET.DAT on the disk in drive B:. The file 
contains 26 records; each record is 28 bytes long: 


record size equ 14 ;Offset of Record Size 
— ;field of FCB 
relative record equ 33 soffset of Relative Record 
~ ;field of FCB 

fcb db 2,"ALPHABETDAT" 
db 25 dup (?) 

buffer db 34 dup(?),"$" 

prompt db "Enter letter: $" 

erlf db 13,10,"5" 

func 21H: set dta buffer ;see Function 1AH 

= open fcb ;see Function OFH 

mov feb{record size],28 ;set record size 

get_char: display prompt ;see Function 09H 
read_kbd_and_echo ;see Function 01H 
cmp al,0DH rjust a CR? 
je all_done yes, go home 
sub al,41H ;convert ASCII code 

sto record # 
mov fcb[relative record],al ;set relative 
record 

display crlf ;see Function 09H 
read ran fcb ;THIS FUNCTION 
display buffer ;see Function 09H 
display crlf 7See Function 09H 
jmp get_char ;get another char. 

all done: close fcb ;See Function 10H 
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Random Write (Function 22H) 


Call 
AH = 22H 
DS :DX 
Opened FCB 
Return 
AL 
00H = Write completed successfully 
01H = Disk full 
02H = DIA too small 


DX must contain the offset from the segment 
address in DS of an opened FCB. The Current Block 
(offset OCH) and Current Record (offset 20H) 
fields are set to agree with the Relative Record 
field (offset 21H), then the record addressed by 
these fields is written from the Disk Transfer 
Address. If the record size is smaller than a 
sector (512 bytes), the records are buffered until 
a sector is ready to write. 


AL returns a code that describes the processing: 
CODE MEANING 

0 Write completed successfully. 

1 Disk is full. 


2 Not enough room at the Disk Transfer Address 
to write one record; write canceled. 
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Macro Definition: write ran macro fcb 
Mov dx,offset fcb 
mov ah, 22H 
int 21H 
endm 


Example: 


The following program prompts for a letter, 
converts the letter to its alphabetic sequence 
(A= 1, B= 2, etc.), then reads and displays the 
corresponding record from a file named 
ALPHABET.DAT on the disk in drive B:. After 
displaying the record, it prompts the user to 
enter a changed record. If the user types a new 
record, it is written to the file; if the user 
just presses RETURN, the record is not replaced. 
The file contains 26 records; each record is 28 
bytes long: 


record size equ 14 ;Offset of Record Size 
a ;field of FCB 
relative _record equ 33 ;Offset of Relative Record 
;field of FCB 
ficb db 2," ALPHABETDAT" 
db 25 dup (?) 
buffer db 26 dup(?),13,10,"$" 


promptl db "Enter letter: $" 

prompt2 db "New record (RETURN for no change): $" 
ecrlf db 13,10,"$" 

reply db 28 dup (32) 

blanks db 26 dup (32) 
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func_ 22H: 


get char: 


all_ done: 


set_dta buffer ;see Function 1AH 


open f£cb :see Function OFH 
mov fcb[record size] ,32 ;set record size 
display promptl see Function 09H 
read kbd and echo ssee Function 01H 
cmp © al,0DH ;just a CR? 
je all done yes, go home 
sub al, 41H convert ASCII 
scode to record # 
mov fcb[relative record] ,al 
~ set relative record 
display crlf ;see Function 09H 
read ran fcb 3;see Function 21H 
display buffer ;see Function 09H 
display crlf ;see Function 09H 
display prompt2 ;see Function 09H 
get_string 27,reply ;see Function OAH 
display crlf :see Function 09H 
cmp reply[1],0 ;was anything typed 
sbesides CR? 
je get_char 7no 
7get another char. 
XxOr bx, bx ;to load a byte 
mov bl,reply{1] ;use reply length as 
;counter 


move_string blanks,buffer,26 ;see chapter end 
move string reply[2] ,buffer,bx ;see chapter end 


write ran fcb ;THIS FUNCTION 
jmp get_char get another character 
close fcb ;see Function 10H 
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File Size (Function 23H) 


Call 
AH = 23H 
DS :DX 
Unopened FCB 


Return 
AL 
00H = Directory entry found 
FFH (255) = No directory entry found 


DX must contain the offset (from the segment 
address in DS) of an unopened FCB. You must set 
the Record Size field (offset OEH) to the proper 
value before calling this function. The disk 
directory is searched for the first matching 
entry. 


If a matching directory entry is found, the 
Relative Record field (offset 21H) is set to the 
number of records in the file, calculated from the 
total file size in the directory entry (offset 
ICH) and the Record Size field of the FCB (offset 
OFH). AL returns 00. 


If no matching directory is found, AL returns FFH 
(255). 


Note: If the value of the Record Size field of 
the FCB (offset OEH) doesn't match the actual 
number of characters in a record, this function 
does not return the correct file size. If the 
default record size (128) is not correct, you must 
set the Record Size field to the correct value 
before using this function. 


Macro Definition: file size macro fcb 
mov dx,offset fcb 
Mov ah, 23H 
int 21H 


Example: 


The following program prompts for the name of a 
file, opens the file to fill in the Record Size 
field of the FCB, issues a File Size system call, 
and displays the file size and number of records 
in hexadecimal: 


fcb db 37 dup (?) 

prompt db “File name: $" 

msgl db “Record length: ",13,10,"S" 

msg2 db “Records: ",13,10,"$" 

erlf db * 13,10,"$" 

reply db 17 dup(?) 

sixteen db 16 

func_23H: display prompt ;see Function 09H 
get_string 17,reply see Function OAH 
cmp reply[1] ,0 ;just a CR? 
jne get_length ino, keep going 
jmp all done ryes, go home 

get_length: display crlf ;see Function 09H 
parse reply[2],fcb ;see Function 29H 
open fcb ;see Function OFH 
file size fcb :THIS FUNCTION 
Mov si,33 ;offset to Relative 

;Record field 

mov di,9 reply in msg 2 

convert it: cmp fcb[si] ,0 digit to convert? 
je . show it ;no, prepare message 


convert fcb[si] ,sixteen,msg_2[di] 
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inc si ;bump n-o-r index 


inc di ;bump message index 
5 convert it ;check for a digit 
show it: convert fcb[14] ,sixteen,msg_1[15] 
display msg 1 ;see Function 09H 
display msg 2 ;see Function 09H 
jmp func_23H get a filename 
all done: close  fcb ;see Function 10H 


Set Relative Record (Function 24H) 


Call 

AH = 24H 

DS :DX 
Opened FCB 


Return 
None 


DX must contain the offset (from the segment 
address in DS) of an opened FCB. The Relative 
Record field (offset 21H) is set to the same file 
address as the Current Block (offset OCH) and 
Current Record (offset 20H) fields. 


Macro Definition: 
set relative record macro fcb 
~ ~ mov dx,offset fcb 
mov ah, 24H 
int 21H 
endm 
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Example: 


The following program copies a file using the 
Random Block Read and Random Block Write system 
calls. It speeds the copy by setting the record 
length equal to the file size and the record count 
to 1, and using a buffer of 32K bytes. It 
positions the file pointer by setting the Current 
Record field (offset 20H) to 1 and using Set 
Relative Record to make the Relative Record field 
(offset 21H) point to the same record as the 
combination of the Current Block (offset OCH) and 
Current Record (offset 20H) fields: 


current record equ 32 ;0ffset of Current Record 
;field of FCB 
file size equ 16 ;0ffset of File Size 
;field of FCB 
fcb db 37 dup (?) 
filename db 17 dup(?) 
promptl db "File to copy: $" ;see Function 09H for 
prompt2 db "Name of copy: $"  ;explanation of $ 
crlf db 13,10,"$" 
file length dw ? 
buffer db 32767 dup(?) 
func_24H: set_dta buffer ;see Function 1AH 
display promptl ;see Function 09H 
get_string 15,filename ;see Function 0AH 
display crlf ;see Function 09H 
parse filename [2] ,fcb ;see Function 29H 
open fcb ;see Function OFH 
mov fcb[current_record] ,0 ;set Current Record 
:field 
set_relative_ record fcb THIS FUNCTION 


mov ax,word ptr fcb[file size] ;get file size 
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mov file length, ax ;Save it for 
ran block write 


ran block read fcb,1l,ax ;see Function 27H 
display prompt2 see Function 09H 
get_ string 15,filename :see Function OAH 
display crlf see Function 09H 
parse filename [2] ,fcb ;see Function 29H 
create  fcb ;see Function 16H 
mov fcb(current_record],0 ;set Current Record 
field 
set_relative_record fcb ;THIS FUNCTION 
mov ax,file_length 3get original file 
; length 
ran block write fcb,1l,ax ;see Function 28H 
close fcb see Function 10H 


Set Vector (Function 25H) 


Call 
AH = 25 
AL 
Interrupt number 
DS :DX 
Interrupt-handling routine 


Return 
None 


Function 25H should be used to set a particular 
interrupt vector. The MS-DOS operating system can 
then manage the interrupts on a per-process basis. 
Note that programs should never set interrupt 
vectors by writing them directly in the low memory 
vector table. 
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DX must contain the offset (to the segment address 
in DS) of an interrupt-handling routine. AL must 
contain the number of the interrupt handled by the 
routine. The address in the vector table for the 
specified interrupt is set to DS:DX. 


Macro Definition: 
set vector macro interrupt,seg_ addr,off_ addr 
Mov al, interrupt 


push ds 
MOV ax,seg addr 
mov ds,ax 
mov dx,off addr 
mov ah, 254 
int 21H 
pop ds 
endm 

Example: 

lds dx, intvector 

mov ah,25H 

mov al, intnumber 

int 21H 


;There are no errors returned 
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Random Block Read (Function 27H) 


Call 
AH = 27H 
DS :DX 
Opened FCB 
CX 
Number of blocks to read 


Return 

AL 
00H 
01H 
02H 
03H 

CX 

- Number of blocks read 


Read completed successfully 
EOF 

End of segment 

EOF, partial record 


DX must contain the offset (to the segment address 
in DS) of an opened FCB. CX must contain the 
number of records to read; if it contains 0, the 
function returns without reading any records (no 
Operation). The specified number of records — 
calculated from the Record Size field (offset OFH) 
—- is read starting at the record specified by the 
Relative Record field (offset 21H). The records 
are placed at the Disk Transfer Address. 
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AL returns a code that describes the processing: 


CODE 


0 


MEANING 


Read completed successfully. 


End-of-—file; no data in the record. 


Not enough room at the Disk Transfer Address 
to read one record without closing the 
segment's boundary; read canceled. 


End-of-file; a partial record was read and 
padded to the record length with zeros. 


CX returns the number of records read; the Current 
Block (offset OCH), Current Record (offset 20H), 
and Relative Record (offset 21H) fields are set to 
address the next record. 


Macro Definition: 


ran_block_read 


mov 
Mov 
mov 
Mov 
int 


endm 


macro fcb,count,rec_ size 


dx,offset fcb 

cx, count 

word ptr fcb[14],rec_size 
ah, 27H 

21H 


See Random Block Write (next function) for an 
example, ; 
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Random Block Write (Function 28H) 


Call 

AH = 28H 

DS :DX 
Opened FCB 

CX 
Number of blocks to write 
(0 = set File Size field) 


Return 

AL 
00H = Write completed successfully 
01H = Disk full 
02H = End of segment 

CX 


Number of blocks written 


DX must contain the offset (to the segment address 
in DS) of an opened FCB; CX must contain either 
the number of records to write or 0. The 
specified number of records (calculated from the 
Record Size field, offset OEH) is written from the 
Disk Transfer Address. The records are written to 
the file starting at the record specified in the 
Relative Record field (offset 21H) of the FCB. If 
CX is 0, no records are written, but the File Size 
field of the directory entry (offset 1CH) is set 
to the number of records specified by the Relative 
Record field of the FCB (offset 21H); allocation 
units are allocated or released, as required. 
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AL returns a code that describes the processing: 
CODE MEANING 

0 Write completed successfully. 

1 Disk full. No records written. 


2 Not enough room at the Disk Transfer Address 
to read one record without crossing the 
segments boundaries; read canceled. 


CX returns the number of records written; the 
Current Block (offset OCH), Current Record (offset 
20H), and Relative Record (offset 21H) fields are 
set to address the next record. 


Macro Definition: 
ran_block write macro fcb,count,rec_size 
mov dx,offset fcb 
mov cx,count 
mov word ptr fcb[14],rec_size 


mov ah, 28H 
int 21H 
endm 


Example: 


The following program copies a file (whose side is 
up to 32K bytes) using the Random Block Read and 
Random Block Write system calls. It speeds the 
copy by specifying a record count equal to the 
file size and a record length of 1, and using a 
buffer of 32K bytes; the file is copied quickly 
with one disk access each to read and write 
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(compare 


to the sample program of Function 27H, 


that specifies a record count of 1 and a record 
length equal to file size): 


current record equ 32 


file size 


fcb 
filename 
promptl 
prompt2 
crlf 
num_recs 
buffer 


func_28H: 


soffset of Current Record field 


equ 16 ;0ffset of File Size field 
db 37 dup (?) 
db 17 dup(?) 
db "File to copy: $" ;see Function 09H for 
db "Name of copy: $" ;explanation of $ 
db 13,10,"$" 
dw ? 
db 32767 dup(?) 
set_dta buffer ;see Function 1AH 
display promptl ;see Function 09H 
get string 15,filename ;see Function OAH 
display erlf ;see Function 09H 
parse filename[2],fcb ;see Function 29H 
open fcb ;see Function OFH 
mov feb[(current record] ,0 
;set Current Record 
;field 
set_relative record fcb ;see Function .24H 
mov ax, word ptr fcb[file size] 
;get file size 
mov num_recs,ax ;save it for 


;ran_block write 
ran_block_read fcb,num_recs,1 ;THIS FUNCTION 


display prompt2 ;see Function 09H 
get string 15,filename see Function OAH 
display crié ;see Function 09H 
parse filename[2],fcb ;see Function 29H 
create fcb ;see Function 16H 
mov fcb(current_record],0 ;set Current 


sRecord field 
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set relative record fcb ;see Function 24H 


TOV ax, file length j;get size of original 
ran block write fcb,num_recs,l ;see Function 28H 
close fcb ssee Function LOH 


Parse File Name (Function 298) 


Call 
AH = 29H 
AL 
Controls parsing (see text) 
DS:SI 
String to parse 
ES :DI 
Unopened FCB 
Return 
AL 
OOH = No wild card characters 
01H = Wild card characters used 
FFH (255) = Drive letter invalid 
DS:SI 
First byte past string that was 
parsed 
ES :DI 


Unopened FCB 


SI must contain the offset (to the segment address 
in DS) of a string (command line) to parse; DI 
Must contain the offset (to the segment address in 
ES) of an unopened FCB. The string is parsed for 
a filename of the form d:filename.ext; if one is 
found, a corresponding unopened FCB is created at 
ES:DI. 
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Bits 0-3 of AL control the parsing and processing. 
Bits 4-7 are ignored: 


BIT VALUE MEANING 
0 0 All parsing stops if a file separator 
is encountered. 
1 Leading separators are ignored. 
1 0 The drive number in the FCB is set 


to 0 (default drive) if the string 
does not contain a drive number. 

1 The drive number in the FCB is not 
changed if the string does not 
contain a drive number. 

2 1 The filename in the FCB is not 
changed if the string does not 
contain a filename. 

0 The filename in the FCB is set to 
8 blanks if the string does not 
contain a filename. 

3 1 The extension in the FCB is not 
changed if the string does not 
contain an extension. 

0 The extension in the FCB is set to 
3 blanks if the string does not 
contain an extension. 


If the filename or extension includes an asterisk 
(*), all remaining characters in the name or 
extension are set to question mark (?). 

Filename separators: 


>. ro, = +/" —] \ <> | space tab 
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Filename terminators include all the filename 
separators plus any control character. A filename 
cannot contain a filename terminator; if one is 
encountered, parsing stops. 


If the string contains a valid filename: 


1. AL returns 1 if the filename or extension 
contains a wild card character (* or ?); AL 
returns 0 if neither the filename nor 
extension contains a wild card character. 


2. DS:SI point to the first character following 
the string that was parsed. 


ES:DI point to the first byte of the unopened 
FCB. 


T£ the drive letter is invalid, AL returns FFH 
(255). If the string does not contain a valid 
filename, ES:DI+l points to a blank. 


Macro Definition: 
parse macro string,fcb 
lea si, string 


lea di,£cb 

push es 

push ds 

pop es 

mov al,OFH :;bits 0, 1, 2, 3 on 
mov ah,29H 

int 21H 

pop es 

endm 


Example: 


The following program verifies the existence of 
the file named in reply to the prompt: 


feb db 37 dup (?) 

prompt db "Filename: $" 

reply db 17 dup(?) 

yes db "PILE EXISTS",13,10,"$" 

no db "PILE DOES NOT EXIST",13,10,"$" 

func 29H: display prompt ;see Function 09H 

get_string 15,reply ;see Function OAH 

parse reply[2],fcb ;THIS FUNCTION 
search first fcb ;see Function 11H 
cmp al,FFH 7dir. entry found? 
je not_there ;no 
display yes ;see Function 09H 

: jmp continue 

not_there: display no 

continue: é 


Get Date (Function 2AH) 


Call 
AH = 2AH 


Return 
CX 
Year (1980 - 2099) 
DH 
Month (1 - 12) 
DL 
Day (1 - 31) 
AL 
Day of week (0=Sun., 6=Sat.) 
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This function returns the current date set in 
MS-DOS as binary numbers in CX and Dx: 


CX Year (1980-2099) 

DH Month (1 = January, 2 = February, etc.) 
DL Day (1-31) 

AL Day of week (0 = Sunday, 1 = Monday, etc.) 


Macro Definition: 
get_date macro 


mov ah,2AH 
int 21H 
endm 


See Set Date (next function) for an example. 


Set Date (Function 2BH) 


AH = 2BH 
CX 
Year (1980 — 2099) 
DH 
Month (1 - 12) 
DL 
Day (1 - 31) 


Return 
AL 
OOH = Date was valid 
FFH (255) = Date was invalid 
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Registers CX and DX must contain a valid date in 
binary: 


CX Year (1980-2099) 
DH Month (1 = January, 2 = February, etc.) 
DL Day (1-31) 


If the date is valid, the date is set and AL 
returns 0. If the date is not valid, the function 
is canceled and AL returns FFH (255). 


Macro Definition: 
set date macro year ,month,day 
ot mov cx, year 
mov dh ,month 
mov d1,day 
MOV ah, 2BH 
int 21H 
endm —~ 


Example: 
The following program gets the date, increments 


the day, increments the month or year, if 
necessary, and sets the new date: 


month db 31,28,31,30,31,30,31,31,30,31,30,31 
func 2BH: get date ;see Function 2AH 
as int. dl ;increment day 

xXOr bx, bx *so BL can be used as index 
mov b1,dh ;move month to index register 
dec bx ymonth table starts with 0 
cmp dl,month[bx] ;past end of month? 
jle month_ok sno, set the new date 
Mov di,l ryes, set day to l 
inc dh sand increment month 
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cmp dh,12 spast end of year? 


jle Mmonth_ok no, set the new date 
mov dh,1 yes, set the month to 1 
inc Cx increment year 


month_ok: set date cx,dh,dl  ;THIS FUNCTION 


Get Time (Function 2CH) 


Call 
AH = 2CH 


Return 
CH 

Hour (0 - 23) 
CL 

Minutes (0 - 59) 
DH 

Seconds (0 - 99) 
DL 

Hundredths (0 - 99) 


This function returns the current time set in 
MS-DOS as binary numbers in CX and Dx: 


CH Hour (0-23) 

CL Minutes (0-59) 

DH Seconds (0-59) 

DL Hundredths of a second (0-99) 


Macro Definition: 
get_time macro 


mov ah,2CH 
int 21H 
endm 
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Example: 


The following program continuously displays the 
time until any key is pressed: 


time db "00:00:00.00",13,10,"s" 

ten db 10 

func_2CH: get_time ;THIS FUNCTION 
convert ch, ten, time ;see end of chapter 


convert cl,ten,time[3] ;see end of chapter 
convert dh,ten,time[6] ;see end of chapter 
convert dl,ten,time[9] ;see end of chapter 


display time ;see Function 09H 
check_kbd status ssee Function OBH 

cmp al,FFH has a key been pressed? 
je all done ryes, terminate 

jmp func_2CH no, display time 


Set Time (Function 2DH) 


Call 
AH = 2DH 
CH 

Hour (0 - 23) 
CL 

Minutes (0 - 9) 
DH 

Seconds (0 - 59) 
DL 

Hundredths (0 - 99) 


Return 
AL 
OOH = Time was valid 
FFH (255) = Time was invalid 
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Registers CX and DX must contain a valid time in 
binary: 


CH Hour (0-23) 

CL Minutes (0-3) 

DH Seconds (0-59) 

DL Hundredths of a second (0-99) 


If the time is valid, the time is set and AL 
returns 0. If the time is not valid, the function 
is canceled and AL returns FFH (255). 


Macro Definition: 
set_time macro hour,minutes,seconds, hundredths 
MOV ch, hour 
mov cl,minutes 
Mov dh, seconds 
mov d1,hundredths 
mov ah, 2DH 
int 21H 


Example: 


The following program sets the system clock to 0 
and continuously displays the time. When a 
character is typed, the display freezes; when 
another character is typed, the clock is reset to 
0 and the display starts again: 


time db "00:00:00.00",13,10,"$" 

ten db 10 

func_2DH: set time 0,0,0,0 ;THIS FUNCTION 

read_clock: get_time ;see Function 2CH 
convert ch,ten,time ;see end of chapter 


convert cl,ten,time[{3] ;see end of chapter 
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convert dh,ten,time{6] ;see end of chapter 
convert dl,ten,time[9] ;see end of chapter 


display time ;see Function 09H 

dir_console io FFH ;see Function 06H 

chip al,00H ;waS a char. typed? 

jne stop ryes, stop the timer 

jmp read clock 7no keep timer on 
stop: read_kbd ;see Function 08H 

jmp func_2DH ;keep displaying time 


Set/Reset Verify Flag (Function 25H) 


Call 

AH = 2FH 

AL 
00H 
01H 


Do not verify 
Verify 


Return 
None 


AL must be either 1 (verify after each disk write) 
or 0 (write without verifying). MS-DOS checks 
this flag each time it writes to a disk. 


The flag is normally off; if necessary, you can 
turn it on when writing critical data to disk. 
Because disk errors are rare and verification 
slows writing, you will probably want to leave it 
off at other times. 


Macro Definition: 

verify macro switch 
MOV al,switch 
mov ah, 2EH 
int 21H 
endm 
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Example: 


The following program copies the contents of a 
single-sided disk in drive A: to the disk in drive 
B:, verifying each write. It uses a buffer of 32K 


bytes: 
on 

off 
prompt 
start 


buffer 


func_2DH: 


Copy: 


disk read 0 


equ l 
equ QO 


db "Source in A, target in B",13,10 
db "Any key to start. $" 

dw 0 

db 64 dup (512 dup(?)) 264 sectors 


display prompt ;see Function 09H 

read_kbd ;see Function 08H 

verify on 7THIS FUNCTION 

mov cx, 19 ;copy 64 sectors 
719 times 

push cx ;Save counter 


abs disk read 0,buffer,64,start 

;see Interrupt 2 
abs disk write 1,buffer,64,start 

;see Interrupt 26H 


add start, 64 7;do next 64 sectors 
pop cx ;restore counter 
loop copy ;do it again 
verify off ;THIS FUNCTION 


,»buffer ,64,start 3;see Interrupt 25 
abs disk write 1,buffer,64,start 
;see Interrupt 26H 


add start, 64 :do next 64 sectors 
pop cx ;restore counter 
loop copy ;do it again 
verify off 
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Get Disk Transfer Address (Function 2FH) 


Return 
Points to Disk Transfer Address 
Function 2FH returns the DMA transfer address. 


Error returns: 


None. 
Example: 
mov ah, 2FH 
int 21H 


;es:bx has current DMA transfer address 


Get DOS Version Number (Function 308) 


Call 
AH = 30H 


Return 
AL 

Major version number 
AH 

Minor version number 
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This function returns the MS-DOS version number. 
On return, AL.AH will be the two-part version 
designation; i.e., for MS-DOS 1.28, AL would be 1 
and AH would be 28. For pre-]1.28, MS-DOS AL = 0. 
Note that version 1.1 is the same as 1.10, not the 
same as 1.01. 


Error returns: 


None. 
Example: 
mov ah, 30H 
int 21H 


al is the major version number 

ah is the minor version number 
bh is the OEM number 

bl:cx is the (24 bit) user number 
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Keep Process (Function 31H) 


Call 
AH = 31H 
AL 
Exit code 
DX 
Memory size, in paragraphs 


Return 
None 


This call terminates the current process and 
attempts to set the initial allocation block toa 
specific size in paragraphs. It will not free up 
any other allocation blocks belonging to that 
process. The exit code passed in AX is 
retrievable by the parent via Function 4DH. 
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This method is preferred over Interrupt 27H and 
has the advantage of allowing more than 64K to be 
kept. 


Error returns: 


None. 
Example: 
mov al, exitcode 
mov dx, parasize 
mov ah, 31H 
int 21H 


ALT-C Check (Function 33H) 


Call 
AH = 33H 


Bi 


Function 
OOH = Request current state 
01H = Set state 

DL (if setting) 


OOH = Off 
O1H = On 
Return 
DL (if requesting current state) 
OOH = Off 
01H = On 
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MS-DOS ordinarily checks for an ALT-C on the 
controlling device only when doing function call 
operations 01H-0CH to that device. Function 33H 
allows the user to expand this checking to include 
any system call. For example, with the ALT-C 
trapping off, all disk I/O will proceed without 
interruption; with ALT-C trapping on, the ALT-C 
interrupt is given at the system call that 
initiates the disk operation. 


Note: Programs that wish to use calls 06H or 07H 
to read ALT-C as data must ensure that the ALT-C 
check is off. 


Error return: 

AL = FF 
The function passed in AL was not in the 
range O:1. 


;I£ al was 0, then dl has the current 
svalue of the ALT-C check 
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Get Interrupt Vector (Function 35H) 


Call 
AH = 354 
= AL 
Interrupt number 


Return 
ES:BX 
Pointer to interrupt routine 
This function returns the interrupt vector 


associated with an interrupt. Note that programs 


should never get an interrupt vector by reading 
the low memory vector table directly. 


Error returns: 


None. 
Example: 
mov ah, 35H 
mov al, interrupt 
int 21H 


7; eS:bx now has long pointer to interrupt routine 
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Get Disk Free Space (Function 36H) 


Call 
= 36H 

DL 
Drive ( 0 = Default, 
1 =A, etc.) 


Return 
BX 
Available clusters 
DX 
Clusters per drive 
CX 
Bytes per sector 
AX 
FFFF if drive number is invalid; 
otherwise sectors per cluster 


This function returns free space on disk along 
with additional information about the disk. 


Error returns: 


AX = FFFF 
The drive number given in DL was 
invalid. 
Example: 
mov ah, 36H 
mov dl,Drive 70 = default, A= 1 
int 21H 

; bx = Number of free allocation units on drive 

; dx = Total number of allocation units on drive 

; cx = Bytes per sector 

+ ax = Sectors per allocation unit 
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Return Country—Dependent Information (Function 
38H) 


Call 
AH = 38H 
DS :DX 
Pointer to 32-byte memory area 
AL 
Function code. In MS-DOS 2.0, 
must be 0 


Return 
Carry set: 
AX 
2 = file not found 
Carry not set: 
DX:DS filled in with country data 


The value passed in AL is either 0 (for current 
country) or a country code. Country codes are 
typically the international telephone prefix code 
for the country. 


If DX = -1, then the call sets the current country 
(as returned by the AL=0 call) to the country code 
in AL. If the country code is not found, the 
current country is not changed. 


Note: Applications must assume 32 bytes of 
information. This means the buffer pointed to by 
DS:DX must be able to accommodate 32 bytes. 


This function is fully supported only in versions 


of MS-DOS 2.01 and higher. It exists in MS-DOS 
2.0, but is not fully implemented. 
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This function returns, in the block of memory 
pointed to by DS:DX, the following information 
pertinent to international applications: 


5 BYTE ASCIZ string 
currency symbol 


2 BYTE ASCIZ string 
thousands separator 


| 2 BYTE ASCIZ string | 


decimal separator 


2 BYTE ASCIZ string 
date separator 


2 BYTE ASCIZ string 
time separator 


$------------- += ----- == —+ 
| 1 BYTE Bit field | 
4----------------- ~~ - = —-+ 
| 1 BYTE | 
Currency places 
4-------~---—-—--- -~----- + 
| 1 BYTE | 
time format 
4+~-----—----------~--- === —+ 
| DWORD 
Case Mapping call 
fan nn + 


2 BYTE ASCIZ string 
data list separator 


l=liz 


The format of most of these entries is ASCIZ (a 
NUL terminated ASCII string), but a fixed size is 
allocated for each field for easy indexing into 
the table. 


The date/time format has the following values: 


0 - USA standard him:s m/d/y 
1 - Europe standard h:m:s d/m/y 
2 - Japan standard y/m/d h:m:s 


The bit field contains 8 bit values. Any bit not 
currently defined must be assumed to have a random 
value. 


Bit 0 = 0 If currency symbol precedes the 
currency amount. 
= 1 If currency symbol comes after 
the currency amount. 
Bit 1 = 0 If the currency symbol immediately 


precedes the currency amount. 
= 1 If there is a space between the 
currency symbol and the amount. 


The time format has the following values: 


0 - 12 hour time 
1 - 24 hour time 


The currency places field indicates the number of 


places which appear after the decimal point on 
currency amounts. 
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The Case Mapping call is a FAR procedure which 
will perform country specific lower-to-uppercase 
mapping on character values from 80H to FFH. It 
is called with the character to be mapped in AL. 
It returns the correct uppercase code for that 
character, if any, in AL. AL and the FLAGS are 
the only registers altered. You can pass this 
routine codes below 80H; however, characters are 
not affected in this range. When there is no 
mapping, AL is not altered. 


Error returns: 
AX 
2 = file not found 
The country passed in AL was not found 
(no table for specified country). 


Example: 


lds dx, blk 
mov ah, 38H 
mov al, Country code 
int 21H 
sAX = Country code of country returned 
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Create Sub-Directory (Function 39H) 


Call 
AH = 39H 
D&A:DS 
Pointer to pathname 


Return 
Carry set: 


AX 


3 
5 

Carry not set: 
No error 


path not found 
access denied 


ou 


Given a pointer to an ASCIZ name, this function 
creates a new directory entry at the end. 


Error returns: 


AX 
3 


Example: 


lds 
mov 
int 


path not found 
The path specified was invalid or 
not found. 

access denied 
The directory could not be created 
(no room in parent directory), the 
directory/file already existed or a 
device name was specified. 


dx, name 
ah, 39H 
21H 
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Remove a Directory Entry (Function 3AH) 


Call 
AH = 3AH 
DS :DX 
Pointer to pathname 
Return 
Carry set: 
AX 
3 = path not found 
5 = access denied 


16 = current directory 
Carry not set: 
No error 


Function 3AH is given an ASCIZ name of a 
directory. That directory is removed from its 
parent directory. 


Error returns: 


AX 
3. = path not found 
The path specified was invalid or not 
found. 
5 = access denied 
The path specified was not empty, not 
a directory, the root directory, or 
contained invalid information. 
16 = current directory 
The path specified was the current 
directory on a drive. 
Example: 
lds dx, name 
mov ah, 3AH 
int 21H 
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Change the Current Directory (Function 3BH) 


Call 
AH = 3BH 
DS :DX 
Pointer to pathname 


Return 
Carry set: 
AX 
3 = path not found 
Carry not set: 
No error 


Function 3BH is given the ASCIZ name of the 
directory which is to become the current 
directory. If any member of the specified 
pathname does not exist, then the current 
directory is unchanged. Otherwise, the current 
directory is set to the string. 


Error returns: 
AX 
3 = path not found 
The path specified in DS:DX either 
indicated a file or the path was 


invalid. 
Example: 
lds dx, name 
mov ah, 3BH 
int 21H 
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Create a File (Function 3CH) 


Call 
AH = 3CH 
DS :DX 
Pointer to pathname 
CX 
File attribute 


Return 
Carry set: 
AX 


5 = access denied 
3 = path not found 

4 = too many open files 
Carry not set: 

AX is handle number 


Function 3CH creates a new file or truncates an 
old file to zero length in preparation for 
writing. If the file did not exist, then the file 
is created in the appropriate directory and the 
file is given the attribute found in CX. The file 
handle returned has been opened for read/write 
access. 


Error returns: 


AX 
3 = path not found 
The path specified was invalid. 
4 = too many open files 


The file was created with the 
specified attributes, but there were 
no free handles available for the 
process, or the internal system tables 
were full. 
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5 = access denied 
The attributes specified in CX 
contained one that could not be 
created (directory, volume ID), a file 
already existed with a more inclusive 
set of attributes, or a directory 
existed with the same name. 


lds dx, name 
mov ah, 3CH 
mov cx, attribute 


: ax now has the handle 


Open a File (Function 308) 


Call 

AH = 3DH 

AL 
Access 
0 = File opened for reading 
1 = File opened for writing 
2 = File opened for both 
reading and writing 

Return 

Carry set: 

AX 
2 = file not found 
4 = too many open files 
5 = access denied 


invalid access 
Carry not set: 
AX is handle number 
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Function 3DH associates a 16-bit file handle with 
a file. 


The following values are allowed: 
ACCESS FUNCTION 


0 file is opened for reading 

1 file is opened for writing 

2 file is opened for both reading 
and writing. 


DS:DX point to an ASCIZ name of the file to be 
opened. 


The read/write pointer is set at the first byte of 
the file and the record size of the file is 1 
byte. The returned file handle must be used for 
subsequent I/O to the file. 


Error returns: 


AX 
2 = file not found 
The path specified was invalid or not 
found. 
4 = too many open files 
There were no free handles available 
in the current process or the internal 
system tables were full. 
5 = access denied 
The user attempted to open a directory 
or volume-id, or open a read-only file 
for writing. 
12 = invalid access 


The access specified in AL was not in 
the range 0:2. 
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Example: 


lds dx, name 
mov ah, 3DH 
mov al, access 
int 21H 


; ax has error or file handle 
; If successful open 


Close a File Handle (Function 3H) 


Call 
AH = 3EH 
BX 
File handle 


Return 
Carry set: 
AX 
6 = invalid handle 
Carry not set: 
No error 


If BX is passed a file handle (like that returned 
by Functions 3DH, 3CH, or 45H), Function 3FH 
closes the associated file. Internal buffers are 
flushed. 


Error return: 
AX 
6 = invalid handle 
The handle passed in BX was not 
currently open. 


Gal all 


Mov bx, handle 
mov ah, 3EH 
int 21H 


Read From File/Device (Function 3FH) 


Call 
AH = 3FH 
DS :DX 
Pointer to buffer 
CX 
Bytes to read 
BX 
File handle 


Return 
Carry set: 
AX 
Number of bytes read 
5 = error set 
6 = invalid handle 
Carry not set: 
AX = number of bytes read 


Function 3FH transfers count bytes froma file 
into a buffer location. It is not guaranteed that 
all "count" bytes will be read; for example, 
reading from the keyboard will read at most one 
line of text. If the returned value is zero, then 
the program has tried to read from the end of 
file. 


All I/O is done using normalized pointers; no 
segment wraparound will occur. 


1-122 


Error returns: 
AX 
5 = access denied 
The handle passed in BX was opened in 
a mode that did not allow reading. 
6 = invalid handle 
The handle passed in BX was not 
currently open. 


Example: 
lds dx, buf 
mov cx, count 
mov bx, handle 
mov ah, 3FH 
int 21H 


; ax has number of bytes read 


Write to a File or Device (Function 40H) 


Call 
AH = 40H 
DS :DX 

Pointer to buffer 
CX 

Bytes to write 
BX 


File handle 


Return 
Carry set: 
AX 
Number of bytes written 
5 = access denied 
6 = invalid handle 
Carry not set: 
AX = number of bytes written 
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Function 40H transfers "count" bytes from a buffer 
into a file. It should be regarded as an error if 
the number of bytes written is not the same as the 
number requested. 


The write system call with a count of zero (CX = 
0) will set the file size to the current position. 
Allocation units are allocated or released as 
required. 


All I/O is done using normalized pointers; no 
segment wraparound will occur. 


Error returns: 
AX 
5 = access denied 
The handle was not opened in a mode that 
allowed writing. 


6 = invalid handle 
The handle passed in BX was not currently 
open. 
Example: 
lds dx, buf 
mov cx, count 


mov bx, handle 
mov ah, 40H 
int 21H 
zax has number of bytes written 
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Delete a Directory Entry (Function 418) 


Call 
AH = 41H 
DS :DX 
Pointer to pathname 


Return 
Carry set: 
AX 
2 = file not found 
5 = access denied 
Carry not set: 
No error 


oil 


Function 41H removes a directory entry associated 
with a filename. 


Error returns: 
AX 
2 = file not found 
The path specified was invalid or not 
found. 


5 = access denied 
The path specified was a directory or 
read-only. 
Example: 


lds dx, name 
Mov ah, 41H 
int 21H 
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Move File Pointer (Function 42H) 


Call 

= 42H 
CX:DX 

Distance to move, in bytes 
AL 

Method of moving: 

(see text) 
BX 

File handle 


Return 
Carry set: 
AX 
1 = invalid function 
6 = invalid handle 
Carry not set: 
DX:AX = new pointer location 


Function 42H moves the read/write pointer 
according to one of the following methods: 


METHOD FUNCTION 
0 The pointer is moved to offset bytes from 
the beginning of the file. 
1 The pointer is moved to the current 
location plus offset. 
2 The pointer is moved to the end of file 


plus offset. 


Offset should be regarded as a 32-bit integer with 
CX occupying the most significant 16 bits. 
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Error returns: 


AX 
1 = invalid function 
The function passed in AL was not in 
the range 0:2. 
6 = invalid handle 
The handle passed in BX was not 
currently open. 
Example: 
mov dx, offsetlow 
mov cx, offsethigh 
mov al, method 
mov bx, handle 
mov ah, 42H 
int 21H 


; dxsax has the new location of the pointer 


Change Attributes (Function 43H) 


Call 
AH = 43H 
DS :DX 
Pointer to pathname 
CX (if AL = 01) 
Attribute to be set 
AL 
Function 
O01 Set to CX 
00 Return in CX 
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Return 


Carry set: 

AX 
1 = invalid function 
3 = path not found 


5 = access denied 
Carry not set: 
CX attributes (if AL = 00) 


Given an ASCIZ name, Function 42H will set/get the 
attributes of the file to those given in CX. 


A function code is passed in AL: 


AL A FUNCTION 
QO Return the attributes of the file in CX. 
Ll Set the attributes of the file to those in CX. 


Error returns: 
AX 
1 = invalid function 
The function passed in AL was not in 
the range 0:1. 
3 = path not found 
The path specified was invalid. 
5 = access denied 
The attributes specified in CX 
contained one that could not be 
changed (directory, volume ID). 


Example: 
lds dx, name 
MOV cx, attribute 
mov al, func 
int ah, 43H 
int 21H 
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I/O Control for Devices (Function 448) 


Call 
AH = 44H 
BX 
Handle 
BL 
Drive (for calls AL = 4, 5 
0 = default, 1 = A, etc.) 
DS :DX 
Data or buffer 
CX 
Bytes to read or write 
AL 
Function code; see text 


Return 
Carry set: 
AX 


invalid function 
access denied 
invalid handle 


13 = invalid data 
Carry not set: 
AL = 2,3,4,5 
AX = Count transferred 
AL = 6,7 
00 = Not ready 
FF = Ready 


Function 44H sets or gets device information 
associated with an open handle, or sends/receives 
a control string to a device handle or device. 
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The following values are allowed for function: 


REQUEST _ FUNCTION 

0 Get device information (returned in DX) 

1 Set device information (as determined 
by DX) 

2 Read CX number of bytes into DS:DX from 
device control channel 

3 Write CX number of bytes from DS:DX to 
device control channel 

4 Same as 2 only drive number in BL 
O=default, A:=1, B:=2,... 

5 Same as 3 only drive number in BL 
O=default, A:=1, B:=2,... 

6 Get input status 

7 Get output status 


This function can be used to get information about 
device channels. Calls can be made on regular 
files, but only calls 0, 6 and 7 are defined in 
that case (AL=0,6,7). All other calls return an 
invalid function error. 


Calls AL=0 and AL=l 
The bits of DX are defined as follows for 
calls AL=0 and Al=l. Note that the upper byte 
MUST be zero on a set call. 


1514131211109 8/76543210— 
fmm pat pt ttt ttt tt ttt 


R| C TJE}|RIS|I|I/I}1I 
e| T SIOJA|PIS|S|SIS 
s| R Reserved DIFIWIEICINICIC 
L E Ci/LJUJO}T 

V L|K|L|TIN 


foam pant tate tated att tot att tt 
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ISDEV = 1 if this channel is a device 
= 0 if this channel is a disk file (Bits 8-15 
= 0 in this case) 
If ISDEV = 1 
EOF = 0 if End Of File on input 
RAW = 1 if this device is in Raw mode 
= 0 if this device is cooked 
ISCLK = 1 if this device is the clock device 
ISNUL = 1 if this device is the null device 
ISCOT = 1 if this device is the console output 
ISCIN = 1 if this device is the console input 
SPECL = 1 if this device is special 
CTRL = 0 if this device can not do control 


strings via calls AL=2 and AL=3. 
CTRL = 1 if this device can process 
control strings via calls AL=2 
and AL=3, 
NOTE that this bit cannot be set. 


If ISDEV = 0 
EOF = 0 if channel has been written 
Bits 0-5 are the block device number for 
the channel (0 = A:, 1 = B:, ...) 


Bits 15,8-13,4 are reserved and should not 
be altered. 


Calls 2..5: 
These four calls allow arbitrary control 
strings to be sent or received from a device. 
The call syntax is the same as the read and 
write calls, except for 4 and 5, which take a 
drive number in BL instead of a handle in BX. 
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An invalid function error is returned if the 
CTRL bit (see above) is 0. 


An access denied is returned by calls AL=4,5 
if the drive number is invalid. 


Calls 6,7: 
These two calls allow the user to check if a 
file handle is ready for input or output. 
Status of handles open to a device is the 
intended use of these calls, but status of a 
handle open to a disk file is allowed, and is 
defined as follows: 


Input : 
Always ready (AL=FF) until EOF 
reached, then always not ready (AL=0) 
unless current position changed via 
LSEEK. 

Output: 
Always ready (even if disk full). 


IMPORTANT 


The status is defined at the time 
the system is CALLED. On future 
versions, by the time control is 
returned to the user from the 
system, the status returned may NOT 
correctly reflect the true current 
state of the device or file. 
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Error returns: 
AX 
1 = invalid function 
The function passed in AL was not in 
the range 0:7. 


5 = access denied (calls AL=4..7) 
6 = invalid handle 
The handle passed in BX was not 
currently open. 
13 = invalid data 
Example: 
mov bx, Handle 
(or mov bl, drive for calls AL=4,5 
O=default,A:=1...) 
mov dx, Data 
(or lds dx, buf and 
MOV cx, count for calls AL=2,3,4,5) 
mov ah, 44H 
mov al, func 
int 21H 


; For calls AL=2,3,4,5 AX is the number of bytes 
; transferred (same aS READ and WRITE). 

; For calls AL=6,7 AL is status returned, AL=0 if 
: status is not ready, AL=OFFH otherwise. 
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Duplicate a File Handle (Function 455) 


Call 
AH = 450 
BX 
File handle 


Return 
Carry set: 
AX 
4 = too many open files 
6 = invalid handle 
Carry not set: 
AX = new file handle 


Function 453 takes an already opened file handle 
and returns a new handle that refers to the same 
file at the same position. 


Error returns: 
AX 
4 = too many open files 
There were no free handles available 
in the current process or the internal 
system tables were full. 


6 = invalid handle 
The handle passed in BX was not 
currently open. 
Example: 
mov bx, fh 
mov ah, 450 
int 21H 


; ax has the returned handle 
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Force a Duplicate of a Handle (Function 46h) 


Call 
AH = 46H 
BX 
Existing file handle 
CX 
New file handle 
Return 
Carry set: 
AX 
4 = too many open files 


6 = invalid handle 
Carry not set: 
No error 


Function 46H takes an already opened file handle 
and returns a new handle that refers to the same 
file at the same position. If there was already a 
file open on handle CX, it is closed first. 


Error returns: 
AX 
4 = too many open files 
There were no free handles available in 
the current process or the internal 
system tables were full. 
6 = invalid handle 
The handle passed in BX was not 
currently open. 


Example: 
mov bx, fh 
Mov cx, newfh 
mov ah, 46H 
int 21H 
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Return Text of Current Directory (Function 47H) 


Call 
AH = 47H 
DS:SI 
Pointer to 64-byte memory area 
DL 
Drive number 


Return 
Carry set: 
AX 
15 = invalid drive 
Carry not set: 
No error 


Function 47H returns the current directory for a 
particular drive. The directory is root-relative 
and does not contain the drive specifier or 
leading path separator. The drive code passed in 
DL is 0=default, 1=A:, 2=B:, etc. 


Error returns: 
AX 
15 = invalid drive 
The drive specified in DL was invalid. 


Example: 
mov ah, 47H 
lds si,area 
mov dl,drive 
int 21H 


; ds:si is a pointer to 64 byte area that 
; contains drive current directory. 


1-136 


Allocate Memory (Function 48H) 


Call 
AH = 48H 
BX 
Size of memory to be allocated 


7 = arena trashed 
= not enough memory 
BX 
Maximum size that could be allocated 
Carry not set: 
AX:0 
Pointer to the allocated memory 


Function 48H returns a pointer to a free block of 
memory that has the requested size in paragraphs. 


Error return: 
AX 
7 


arena trashed 
The internal consistency of the memory 
arena has been destroyed. This is due 
to a user program changing memory that 
does not belong to it. 

8 = not enough memory 

The largest available free block is 

smaller than that requested or there 

is no free block. 
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mov bx, size 
mov ah, 48H 
int 21H 


; ax:0 is pointer to allocated memory 
; 1£ alloc fails, bx is the largest block available 


Free Allocated Memory (Function 49H) 


Segment address of memory 
area to be freed 


Return 
Carry set: 
AX 

7 = arena trashed 
9 = invalid block 
Carry not set: 

No error 


Function 49H returns a piece of memory to the 
system pool that was allocated by Function Request 
49H. 


Error returns: 
AX 
7 = arena trashed 
The internal consistency of the memory 
arena has been destroyed. This is due 
to a user program changing memory that 
does not belong to it. 
9 = invalid block 
The block passed in ES is not one 
allocated via Function Request 49H. 


1-138 


Example: 


mov es, block 
mov ah, 49H 
int 21H 


Modify Allocated Memory Blocks (Function 4AH) 


Call 
AH = 4AH 
ES 
Segment address of memory area 
BX 
Requested memory area size 


7 = arena trashed 
8 = not enough memory 
9 = invalid block 
BX 
Maximum size possible 
Carry not set: 
No error 


Function 4AH will attempt to grow/shrink an 
allocated block of memory. 
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Error return: 
AX 
7 = arena trashed 
The internal consistency of the memory 
arena has been destroyed. This is due 
to a user program changing memory that 
does not belong to it. 
8 = not enough memory 
There was not enough free memory after 
the specified block to satisfy the 
grow request. 
9 = invalid block 
The block passed in ES is not one 
allocated via this function. 


Example: 
mov es, block 
mov bx, newsize 
mov ah, 44H 
int 21H 


; if setblock fails for growing, BX will have the 
; maximum size possible 


Load and Execute a Program (Function 48H) 


Call 
AH = 4BH 
DS :DX 
Pointer to pathname 
ES :BX 
Pointer to parameter block 
AL 
00 = Load and execute program 
03 = Load program 
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Carry set: 
AX 
1 = invalid function 
2 = file not found 
8 = not enough memory 
10 = bad environment 
11 = bad format 
Carry not set: 
No error 


This function allows a program to load another 
program into memory and (default) begin execution 


of it. DS: 


DX points to the ASCIZ name of the file 


to be loaded. ES:BX points to a parameter block 
for the load. 


A function code is passed in AL: 


AL 


FUNCTION 


0 Load and execute the program. A program 


header 


is established for the program and the 


terminate and ALT-C addresses are set to 
the instruction after the EXEC system call. 


3 Load (do not create) the program header, and 


do not 


begin execution. This is useful in 


loading program overlays. 
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For each value of AL, the block has the 
following format: 


AL = 0 -> load/execute program 


fren + 

| WORD segment address of | 
environment. 

on -- + 
DWORD pointer to command | 
line at 80H 

$-—- === + 


DWORD pointer to default 
FCB to be passed at 5CH 


DWORD pointer to default 
FCB to be passed at 6CH 


AL = 3 -> load overlay 


WORD segment address where 
file will be loaded. 


WORD relocation factor to 
be applied to the image. 


All open files of a process are duplicated in the 
child process after an EXEC. This is extremely 
powerful; the parent process has control over the 
meanings of stdin, stdout, stderr, stdaux and 
stdprn. The parent could, for example, write a 
series of records to a file, open the file as 
standard input, open a listing file as standard 
output and then EXEC a sort program that takes its 
input from stdin and writes to stdout. 
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Also inherited (or passed from the parent) is an 
"environment." This is a block of text strings 
(less than 32K bytes total) that convey various 
configuration parameters. The format of the 
environment is as follows: 


(paragraph boundary) 


fen nnn nnn —+ 
| BYTE ASCIZ string 1 | 
penn nnn —+ 
| BYTE ASCIZ string 2 | 
fern nnn af 
2 sil 
| BYTE ASCIZ string n 
in pectertedententastnaanetaiaitaanemeaneatetetanatememaen + 
| BYTE of zero | 
fern —+ 


Typically the environment strings have the form: 
parameter=value 
Use the SET command to manipulate the environment. 


For example, COMMAND.COM might pass its execution 
search path as: 


PATH=A: \BIN;B:\BASIC\LIB 
A zero value of the environment address causes the 


child process to inherit the parent's environment 
unchanged. 
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Error returns: 
AX 
1 


invalid function 
The function passed in AL was not 0, 1 
or 3. 
2 = file not found 
The path specified was invalid or not 
found. 
8 = not enough memory 
There was not enough memory for the 
process to be created. 
10 = bad environment 
The environment was larger than 32Kb. 
ll = bad format 
The file pointed to by DS:DX was an 
EXE format file and contained 
information that was internally 
inconsistent. 


Example: 


lds dx, name 
les bx, blk 

mov ah, 4BH 

mov al, func 
int 21H 


Terminate a Process (Function 4CH) 
Call 
AH = 4CH 
AL 
Return code 


Return 
None 
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Function 4CH terminates the current process and 
transfers control to the invoking process. In 
addition, a return code may be sent. Ali files 
open at the time are closed. 


This method is preferred over all others 
(Interrupt 20H, JMP 0) and has the advantage that 
CS:0 does not have to point to the Program Header 
Prefix. 


Error returns: 
None. 


Example: 
mov al, code 


Mov ah, 4CH 
int 21H 


Retrieve the Return Code of a Child (Function 4DH) 


Call 
AH = 4DH 


Return 


AX 
Exit code 
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Function 4DH returns the Exit code specified by a 
child process. It returns this Exit code only 
once. The low byte of this code is that sent by 
the Exit routine. The high byte is one of the 
following: 


- Terminate/abort 

- ALT-C 

- Hard error 

~ Terminate and stay resident 


WNHrO& 


Error returns: 
None. 


Example: 


mov ah, 4DH 
int 21H 
; ax has the exit code 


‘Find Match File (Function 45H) 


Call 
AH = 4EH 
DS :DX 
Pointer to pathname 
CX 
Search attributes 


Return 
Carry set: 
AX 
2 = file not found 
18 = no more files 
Carry not set: 
No error 
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Function 4EH takes a pathname with wild-card 
characters in the last component (passed in 
DS:DX), a set of attributes (passed in CX) and 
attempts to find all files that match the pathname 
and have a subset of the required attributes. A 
datablock at the current DMA is written that 
contains information in the following form: 


find buf reserved DB 21 DUP (?); Reserved* 


find _buf_attr DB ? ; attribute found 
find buf time DW ? ; time 

find buf date DW ? ; date 

find buf size 1 DW ? ; low(size) 

find buf size h DW ? ; high(size) 

find buf _pname DB 13 DUP (?) ; packed name 


find buf ENDS 
*Reserved for MS-DOS use on subsequent find nexts 


To obtain the subsequent matches of the pathname, 
see the description of Function 4FH. 


Error returns: 
AX 
2 = file not found 
The path specified in DS:DX was an 
invalid path. 
18 = no more files 
There were no files matching this 
specification. 


mov ah, 4EH 
lds dx, pathname 
mov cx, attr 


; dma address has datablock 
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Step Through a Directory Matching Files (Function 
4FH) 


Call 
AH = 4FH 


Return 
Carry set: 
AX 
18 = no more files 
Carry not set: 
No error 


Function 4FH finds the next matching entry ina 
directory. The current DMA address must point at 
a block returned by Function 4EH (see Function 
4EH) . 


Error returns: 

AX 

18 = no more files 
There are no more files matching this 
pattern. 


Example: 


; dma points at area returned by Function 4FH 
mov ah, 4FH 
int 2]H 

; next entry is at dma 
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Return Current Setting of Verify After Write Flag 
(Function 54H) 


Call 
AH = 54H 


Return 
AL 
Current verify flag value 


The current value of the verify flag is returned 
in AL. 


Error returns: 


None. 
Example: 
mov ah, 54H 
int 21H 


; al is the current verify flag value 


Move a Directory Entry (Function 568) 


Call 

AH = 56H 

DS :DX 
Pointer to pathname of 
existing file 

ES:DI 
Pointer to new pathname 
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Return 
Carry set: 


2 = file not found 
= access denied 
17 = not same device 
Carry not set: 
No error 


Function 56H attempts to rename a file into 
another path. The paths must be on the same 
device. 


Error returns: 
AX 
2 = file not found 
The filename specifed by DS:DX was 
not found. 


5 = access denied 
The path specified in DS:DX was a 
directory or the file specified by 
ES:DI exists or the destination 
directory entry could not be created. 
17 = not same device 
The source and destination are on 
different drives. 
Example: 
lds dx, source 
les di, dest 
MOV ah, 56H 
int 21H 
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Get/Set Date/Time of File (Function 57H) 


= 57H 


i=) 
Oo 
| 


= get date and time 
01 = set date and time 


File handle 
CX (if AL = 01) 

Time to be set 
DX (if AL = 01) 

Date to be set 


Return 

Carry set: 

AX 
1 = invalid function 
6 = invalid handle 

Carry not set: 

No error 

CX/DX set if function 0 


Function 57H returns or sets the last-write time 
for a handle. These times are not recorded until 


the file is closed. 
A function code is passed in AL: 


AL FUNCTION 


Q Return the time/date of the handle in CX/Dx 
1 Set the time/date of the handle to CX/DX 
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Error returns: 


AX 
1 = invalid function 
The function passed in AL was not in 
the range 0:1. 
6 = invalid handle 
The handle passed in BX was not 
currently open. 
Example: 
mov ah, 5/H 


mov al, func 
mov bx, handle 
; if al = 1 then the next two are mandatory 
mov cx, time 
mov dx, date 


: if al = 0 then cx/dx has the last write 
; time/date for the handle. 


1.8 MACRO DEFINITIONS FOR MS-DOS SYSTEM CALL 
EXAMPLES 


Note: These macro definitions apply to system 
call examples 00H through 57H. 


KEKKKEKRKKRKEKEKEKKEKKK 


Interrupts 
KKKKKEKKEKREKREEKEKKKE 


“se 58 Ne Se Ne 
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7;ABS DISK READ 


abs disk read macro disk, buffer ,num sectors, f irst_sector 


mov 
mov 
mov 
mov 
int 
popf 
endm 


. 
‘ 


abs_disk_write 


i 
stay resident macro last_instruc 


al,disk 

bx,offset buffer 

cx,num sectors 

dx, first_sector 

25 ;interrupt 258 


7ABS DISK WRITE 


macro disk,buffer,num_sectors, fir st_sector 


al,disk 

bx,offset buffer 

cx,num_ sectors 

dx, first sector 

26H - yinterrupt 26H 


;STAY_RESIDENT 


mov dx,offset last_instruc 
inc dx 
int 27H ;interrupt 27H 
endm 
rrererrrrr ert rere, 
: Functions 
p ERA RKKRKERERRERER 
read_kbd_and_echo macro ;READ_KBD AND ECHO 
mov ah,1 ;function 1 
int 21H 
endm 
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display char macro character 


mov 
MOV 
int 
endm 


. 
’ 


aux_input macro 
mov 
int 
endm 


' 
aux output macro 


Mov 
int 
endm 

7 rpage 


print char macro 


mov 
mov 
int 
endm 


di,character 
ah,2 
21H 


ah,3 
21H 


ah,4 
21H 


character 
dl1,character 
ah,5 

21H 


i 
dir_console_io macro switch 


MOV 


dal,switch 
ah,6 
21H 


’ 
dir _console_input macro 


mov 
int 
endm 

; 

read_kbd macro 
mov 
int 
endm 


™ 


ah,7 
21H 


ah;8 
21H 
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;DISPLAY CHAR 


;function 2 


;AUX_INPUT 
sfunction 3 


;AUX_OUTPUT 
:function 4 


;PRINT_CHAR 


sfunction 5 


;DIR_CONSOLE_IO 


:function 6 


;DIR_CONSOLE_INPUT 


;function 7 


;READ_KBD 
;function 8 


display macro string 


mov dx,offset string 
mov ah,9 
int 21H 
endm 
get_string macro. limit,string 
mov string, limit 
mov dx,offset string 
mov ah,OAH 
int 21H 
endm 
check_kbd_status macro 
mov ah,OBH 
int 21H 
endm 
flush_and read kbd macro switch 
mov al,switch 
mov ah ,OCH 
int 21H 
endm 
reset disk macro 
mov ah ,ODH 
int 21H 
endm 
7 ;page 
select disk macro disk 
Mov dl,disk[-65] 
mov ah ,OEH 
int 21H 
endm 
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?DISPLAY 


;function 9 


;GET_STRING 


;function OAH 


;CHECK_KBD STATUS 


;function OBH 


;FLUSH_AND READ KBD 


function OCH 


;RESET DISK 
;function ODH 


;}SELECT_DISK 


;function OFH 


=e 


open 


macro 
mov 
mov 
int 
endm 


macro 
mov 
mov 
int 
endm 


, 
search first macro 


mov 
mov 
int 
endm 


, 
search next macro 


delete 


' 
read_ seq 


mov 
mov 
int 
endm 


macro 
mov 
Mov 
int 
endm 


macro 
mov 
mov 
int 
endm 


fcb 

dx,offset fcb 
ah ,OFH 

21H 


fcb 
dx,offset fcb 
ah, 10H 

21H 


fcb 
dx,offset fcb 
ah, 11H 


dx,offset fcb 


fcb 

dx,offset fcb 
ah,13H 

21H 


fcb 
dx,offset fcb 
ah, 14H 

21H 
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;OPEN 


;function OFH 


7CLOSE 


:function LOH 


;SEARCH_ FIRST 


sfunction 11H 


;SEARCH_NEXT 


sfunction 12H 


; DELETE 


sfunction 13H 


;READ_ SEQ 


:function 14H 


. 
' 


write seq macro 
mov 
MOV 
int 
endm 


a 
create macro 
mov 
mov 
int 
endm 


rename 


mov 
int 
endm 


La 
current disk macro 


mov 
int 
endm 
, 
set dta macro 
mov 
mov 
int 
endm 


alloc_table macro 


mov 
int 
endm 


ficb 

dx,offset fcb 
ah,13 

21H 


fcb 

dx,offset fcb 
ah, 16H 

21H 


fcb ,newname 


dx,offset fcb 


ah,17H 


buffer 
dx,offset buffer 
ah, 1AH 

21H 


ah, 1BH 
21H 


nad Fs 


;WRITE_SEQ 


sfunction 154 


; CREATE 


sfunction 16H 


; RENAME 


sfunction 17H 


;CURRENT DISK 
sfunction 19H 


;SET_DTA 


sfunction 1AH 


;ALLOC_TABLE 
sfunction 18H 


' 

read_ran macro 
mov 
mov 
int 
endm 


‘ 

write ran macro 
mov 
mov 
int 
endm 


‘ 

file size macro 
mov 
mov 
int 
endm 


set_relative record 
mov 
mov 
int 
endm 
;;page 


set_vector macro 
push 
mov 


fcb 
dx,offset fcb 
ah, 21H 

21H 


fcb 

dx,offset fcb 
ah, 22H 

21H 


fcb 

dx,offset fcb 
ah, 23H 

21H 


macro fcb 
dx,offset fcb 
ah, 24H 

21H 


;READ_RAN 


sfunction 21H 


;WRITE._RAN 


sfunction 22H 


;FILE SIZE 


sfunction 23H 


;SET_RELATIVE RECORD 


s;function 24H 


interrupt,seg addr,off_addr ;SET_VECTOR 


ds 

ax,seg addr 
ds,ax 

dx ,off_addr 
al, interrupt 
ah, 258 

21H 
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sfunction 254 


create prog seg 
Mov 
TOV 
int 
endm 


ran block read 


int 
endm 


‘ 
ran_block write 


: 
parse macro 


get_date macro 


macro seg addr ;CREATE PROG SEG 
dx,seg_ addr 
ah,26H ;function 26H 
21H 


macro fcb,count,rec size ;RAN_ BLOCK READ 


dx,offset fcb 


cx, count 

word ptr fcb[14] ,rec_size 

ah,27H sfunction 27H 
21H 


macro fcb,count,rec size ;RAN BLOCK WRITE 


dx,offset fcb 


cx, count 

word ptr fcb{14),rec_size 

ah, 28H sfunction 28H 
21H 

filename, fcb ; PARSE 


si,offset filename 
di,offset fcb 


ah,29H ;function 29H 


;GET_DATE 
ah, 2AH ;function 2AH 
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i ;page 
set date 


' 
get_time 


=~ 


set time 


year ,month ,day 7SET_DATE 
cx,year 
dh ,month 
dl,day 
ah, 2BH :function 2BH 
21H 

;GET_TIME 
ah, 2CH ;function 2CH 
21H 

;SET_TIME 


hour ,minutes, seconds, hundredths 

ch, hour 

cl,minutes 

dh, seconds 

dl, hundredths 

ah, 2DH ;function 2DH 
21H 


switch ; VERIFY 
al,switch 

ah, 2EH ;function 2EH 
21H 
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. 
r 
. 
' 
. 
Ud 


General 


KKEKKEKEREKKERKEKKEKEKKE 


g RREKRERERKERRRERERE 


move_string macro source,destination,num_bytes 
;MOVE_ STRING 


push 
mov 
MOV 


rep movs 
‘ 
convert macro 


table db 
start: mov 


es 
ax,ds 

es,ax 

es:data 

si, source 

di, destination 
cx,num_bytes 
es:destination, source 
es:nothing 

es 


value base ,destination 
table, start 

start 

"01234 56789ABCDEF" 

al, value 

ah, ah 


bl,al 

al,cs: table [bx] 
destination,al 
bl,ah 

al,cs: table [bx] 
destination [1] ,al 
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irpage 


convert _to_ binary macro string ,number , value 


ten 
start: 


calc: 


mult: 


“no_mult: 


;CONVERT TO BINARY 


local ten, start,calc,mult,no mult 
jmp start 
db 10 
mov value ,0 
XOr CX,CX 
mov cl,number 
xXOL si,si 
xOr ax,ax 
mov al,string[si] 
sub al,48 
cmp CX,2 
jl no_mult 
push cx 
dec cx 
mul cs:ten 
loop mult 
pop Cx 
add value ,ax 
ine si 
loop calc 
endm 
convert date macro dir entry 
mov dx,word ptr dir_entry[25] 
mov cl,5 
shr dl,cl 
MOV dh ,dir_entry[25] 
and dh,1fh 
XOK cx, Cx 
mov cl,dir_ entry [26] 
shr cl,l 
add cx, 1980 
endm 
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2. MS-DOS 2.1 DEVICE DRIVERS 


2.1 INTRODUCTION 


A device driver is a binary .COM file with all of 
the code in it to manipulate the hardware and 
provide a consistent interface to MS-DOS. In 
addition, it has a special header at the 
beginning that identifies it as a device driver, 
defines the strategy and interrupt entry points, 
and describes various attributes of the supported 
device. 


Note: For device drivers, the file must not 

use the ORG 100H (like .COM files). Because it 
does not use the Program Segment Prefix, the 
device driver is simply loaded; therefore, the 
file must have an origin of zero (ORG 0 or no ORG 
statement). 


There are two kinds of device drivers: 

o Character device drivers 

o Block device drivers 

Character devices are designed to perform serial 
character I/O like CON, AUX, and PRN (that is, 
LST). These devices are named (i.e., CON, AUX, 


CLOCK, etc.), and users may open channels (handles 
or FCBs) to do I/O to them. 


Block devices are similar in capability to the 
disk drives on the system. They can perform 
random I/O in pieces called blocks (such as a 
physical sector size). These devices are not 
named as the character devices are, and therefore 
cannot be opened directly. Instead, they are 
identified via the drive letters (A:, Bs, C:, 
and so on). 


Block devices also have units. A single driver 
may be responsible for one or more disk drives. 
For example, block device driver ALPHA may be 
responsible for drives A:,B:,C: and Ds. 
Consequently, it has four units (0-3) defined; 
therefore, it takes up four drive letters. The 
position of the driver in the list of all drivers 
determines which units correspond to which driver 
letters. If driver ALPHA is the first block 
driver in the device list, and it defines 4 units 
(0-3), then they will be A:,B:,C: and D:. If BETA 
is the second block driver and defines three units 
(0-2), then they will be E:,F: and G:, and so on. 
MS~DOS 2.1 is not limited to 16 block device 
units, as previous versions were. The theoretical 
limit is 63 (2° — 1), but it should be noted that 
after 26 the drive letters are unconventional 
characters (such as ], \, and *). 


Note: Character devices cannot define multiple 
units because they have only one name. 


2.2 DEVICE HEADERS 


A device header is required at the beginning of a 
device driver. Figure 2-1 shows a device header. 


Figure 2-1: Sample Device Header 

(Refer to text for explanation) 
DWORD pointer to next device 
(Must be set to -1) 
WORD attributes 


Bit 15 = 1 if char device, 0 if block 
if bit 15 is 1 


Bit 0 = 1 if current sti device 
Bit 1 = 1 if current sto output 
Bit 2 = 1 if current NUL device 
Bit 3 = 1 if current CLOCK dev 

Bit 4= 1 if special 

Bits 5-12 Reserved; must be set 


to 0 
Bit 14 is the IOCTL bit 
Bit 13 is the NON IBM FORMAT bit 


fanaa nn = + 
WORD pointer to device strategy 
entry point | 
$--------------------------------------- + 
WORD pointer to device interrupt 
entry point 
Sn + 


8-BYTE character device name field 
Character devices set a device name. 
For block devices the first byte is 
the number of units. 


The device entry points are words. They must be 
offsets from the same segment number used to point 
to this table. For example, if XXX:YYY points to 
the start of this table, then XXX:strategy and 
XXX: interrupt are the entry points. 


2.2.1 POINTER TO NEXT DEVICE FIELD 


The pointer to the next device header field is a 
double word field (offset followed by segment) 
that is set by MS-DOS to point at the next driver 
in the system list at the time the device driver 
is loaded. This field must be set to -1 prior to 
load (when it is on the disk as a file) unless 
there is more than one device driver in the file. 
If there is more than one driver in the file, the 
first word of the double word pointer should be 
the offset of the next driver's Device Header. 


Note: If there is more than one device driver in 
the .COM file, the last driver in the file must 
have its pointer to the next Device Header field 
set to -l. 


2.2.2 ATTRIBUTE FIELD 


The attribute field is used to tell the system 
whether this device is a block or character device 
(bit 15). Most other bits are used to give 
selected character devices certain special 
treatment. (Note that these bits mean nothing on 
a block device.) For example, assume you have a 
new device driver, and you want it to be the 
standard input and output. Besides installing the 
driver, you must tell MS-DOS that you want the new 
driver to override the current standard input and 
standard output (the CON device). This is 
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accomplished by setting the attributes to the 
desired characteristics, so you would set bits 0 
and 1 to 1 (note that they are separate). 
Similarly, a new CLOCK device could be installed 
by setting that attribute. (Refer to Chapter 2.7 
for more information.) Although there is a NUL 
device attribute, the NUL device cannot be 
reassigned. This attribute exists so that MS-DOS 
can determine if the NUL device is being used. 


The SPECIAL bit indicates that this device is the 
only one which will accept INT 29 (optimized 
console output) requests, bypassing the normal 
console I/O layers which standarize, but slow 
down, console output. This should only be used 
for a CON replacement. 


The NON IBM FORMAT bit applies only to block 
devices and affects the operation of the BUILD BPB 
(Bios Parameter Block) device call. This should 
be set to 1 unless your driver is for IBM 
compatible floppies. (Refer to Chapter 2.5.3 for 
further information on this call.) 


The other bit of interest is the IOCTL bit, which 
has meaning on character and block devices. This 
bit tells MS-DOS whether the device can handle 
control strings (via the IOCTL system call, 
Function 444). 


If a driver cannot process control strings, it 
should initially set this bit to 0. This tells 
MS-DOS to return an error if an attempt is made 
(via Function 44H) to send or receive control 
strings to this device. A device which can 
process control strings should initialize the 
IOCTL bit to 1. For drivers of this type, MS-DOS 


will make calls to the IOCTL INPUT and OUTPUT 
device functions to send and receive IOCIL 
strings. 


The IOCTL functions allow data to be sent and 
received by the device for its own use (for 
example, to set baud rate, stop bits, and forms 
length), instead of passing data over the device 
channel as does a normal read or write. The 
interpretation of the passed information is up to 
the device, but it must not be treated as a normal 
I/O request. 


2.2.3 STRATEGY AND INTERRUPT ROUTINES 


These two fields are the pointers to the entry 
points of the strategy and interrupt routines. 
They are word values, so they must be in the same 
segment as the Device Header. The strategy entry 
is used for MS-DOS to pass a Request Header 
(explained later) to the driver. The interrupt 
routine services and returns the requests. The 
strategy handler is responsible for queuing (and 
the interrupt routine dequeuing) if over one 
request is supported by the driver concurrently. 


2.2.4 NAME FIELD 


This is an 8-byte field that contains the name of 
a character device or the number of units of a 
block device. If it is a block device, the number 
of units can be put in the first byte. This is 
optional, because MS-DOS will fill in this 
location with the value returned by the driver's 
INIT code. Refer to Chapter 2.4 for more 
information. 


2.3 HOW TO CREATE A DEVICE DRIVER 


To create a device driver that MS-DOS can 

install, you must write a binary file with a 
Device Header at the beginning of the file. For 
device drivers, the code should be originated 

at O instead of LOOH. The link field (pointer to 
next Device Header) should be -l, unless there is 
more than one device driver in the file. The 
attribute field and entry points must be set 
correctly. 


If it is a character device, the name field should 
be filled in with the name of that character 
device. The name can be any legal 8-character 
filename (but need not match the driver's .COM 
filename). 


MS-DOS always processes installable device 

Arivers before handling the default devices, so to 
install a new CON device, simply name the device 
CON. For CON, remember to set the standard input 
device and standard output device bits in the 
attribute word on a new CON device. The scan of 
the device list stops on the first match, so the 
installable device driver takes precedence. 


Note: Because MS-DOS can install the driver 
anywhere in memory, care must be taken in any far 
memory references. You should not expect that 
your driver will always be loaded in the same 
place every time. 
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2.4 INSTALLATION OF DEVICE DRIVERS 


MS-DOS 2.1 allows new device drivers, specified in 
your CONFIG.SYS file, to be installed dynamically 
at boot time. This is accomplished by INIT code in 
the BIOS, which reads and processes the CONFIG.SYS 
file. 


MS-DOS calls upon the device drivers to perform 
their function in the following manner: 


MS-DOS makes a far call to strategy entry, 
and passes (in a Request Header) the 
information describing the functions of the 
device driver. 


This structure allows you to program an 
interrupt-driven device driver. For example, you 
may want to perform local buffering in a printer. 


2.5 REQUEST HEADER 


When MS-DOS calls a device driver to perform a 
function, it passes a Request Header in ES:BX to 
the strategy entry point. This is a fixed length 
header, followed by data pertinent to the 
operation being performed. Note that it is 

the device driver's responsibility to preserve 
the machine state (for example, save all registers 
on entry and restore them on exit). There is 
enough room on the stack when strategy or 
interrupt is called to do about 20 pushes. If 
more stack is needed, the driver should set up 
its own stack. 


The following figure illustrates a Request Header. 


Figure 2-2: Request Header 
REQUEST HEADER -> 


BYTE length of record 
Length in bytes of this 
Request Header 


BYTE unit code 

The subunit the operation 
is for (minor device). 

No meaning on character 


devices. 
sfc eee cern eo a ee + 
| BYTE command code | 
fe err + 
| WORD status | 
ae nnn nn + 


8 bytes RESERVED 


2.5.1 UNIT CODE 


The unit code field identifies which unit in 

your device driver the request is for. For 
example, if your device driver has 3 units 
defined, then the possible values of the unit code 
field would be 0, 1, and 2. 
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2.5.2 COMMAND CODE FIELD 


The command code field in the Request header can 
have the following values: 


COMMAND 
CODE FUNCTION 
0 INIT 
1 MEDIA CHECK (Block only, no operation 
for character) 
2 BUILD BPB_ (Block only, no operation 
for character) 
3 IOCTL INPUT (Only called if device has 
IOCTL) 
4 INPUT (read) 
5 NON-DESTRUCTIVE INPUT NO WAIT 
(Character devices only) 
6 INPUT STATUS (Character devices only) 
7 INPUT FLUSH (Character devices only) 
8 OUTPUT (write) 
9 OUTPUT (write) with verify 
. 10 OUTPUT STATUS (Character devices only) 
ll OUTPUT FLUSH (Character devices only) 
12 IOCTL OUTPUT (Only called if device 
has IOCTL) 


2.5.3 MEDIA CHECK AND BUILD BPB 


MEDIA CHECK and BUILD BPB are used with block 
devices only. 
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MS~DOS calls MEDIA CHECK first for a drive unit. 
MS-DOS passes its current media descriptor byte 
(refer:to Chapter 2.6.4). MEDIA CHECK returns one 
of the following results: 


Oo Media Not Changed — current DPB and media byte 
are OK. 


Oo Media Changed -- Current DPB and media are 
wrong. MS-DOS invalidates any buffers for this 
unit and calls the device driver to build the 
BPB with media byte and buffer. 


o Not Sure — If there are dirty buffers (buffers 
with changed data, not yet written to disk) for 
this unit, MS-DOS assumes the DPB and media 
byte are OK (media not changed). If nothing is 
dirty, MS-DOS assumes the media has changed. 

It invalidates any buffers for the unit, and 
calls the device driver to build the BPB with 
media byte and buffer. 


o Error — If an error occurs, MS-DOS sets the 
error code accordingly. 


MS-DOS will call BUILD BPB under the following 
conditions: 


Oo If Media Changed is returned 


o If Not Sure is returned, and there are no dirty 
buffers 
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The BUILD BPB call also gets a pointer toa 
one-sector buffer. What this buffer contains is 
determined by the NON IBM FORMAT bit in the 
attribute field. If the bit is zero (device is 
IBM format-compatible), then the buffer contains 
the first sector of the first FAT. The FAT ID 
byte is the first byte of this buffer. NOTE: The 
BPB must be the same, as far as location of the 
FAT is concerned, for all possible media because 
this first FAT sector must be read before the 
actual BPB is returned. If the NON IBM FORMAT bit 
is set, then the pointer points to one sector of 
scratch space (which may be used for anything). 


2.5.4 STATUS WORD 
The following figure illustrates the status 
word in the Request Header. 


15 1413121110 9 8 765 43 21 +90 
Sn nn ne ee ae a oars 


E B | D 
R RESERVED U | O | ERROR CODE (bit 15 on) 
R S | N 


foam pant tp tt tt tt tt tp ptt 
The status word is zero on entry and is set by 

the driver interrupt routine on return. 

Bit 8 is the done bit. When set, it means the 


operation is complete. For MS-DOS 2.1, the 
driver sets it to 1 when it exits. 
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Bit 15 is the error bit. If it is set, then the 
low 8 bits indicate the error. The errors are: 


0 Write protect violation 
1 Unknown Unit 

2 Drive not ready 

3 Unknown command 

4 CRC error 

5 Bad drive request structure length 
6 Seek error 

7 Unknown media 

8 Sector not found 

9 Printer out of paper 

A Write fault 

B Read Fault 

C General failure 


Bit 9 is the busy bit, which is set only by status 
calls. 


For output on character devices: If bit 9 (BUSY) 
is 1 on return, a write request (if made) would 
wait for completion of a current request. If the 
busy bit is 0, there is no current request, and a 
write request (if desired) could start 
immediately. 


For input on character devices with a buffer: If 
bit 9 is 1 om return, a read request would go to 
the physical device. If it is 0 on return, then 
there are characters in the device buffer and a 
read would return quickly. It also indicates that 
something has been typed. MS-DOS assumes all 
character devices have an input type-ahead buffer. 
Devices that do not have a type-ahead buffer 
should always return busy=0 so that MS-DOS will 
not continuously wait for something to get into a 
buffer that does not exist. 
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One of the functions defined for each device is 
INIT. This routine is called only once when the 
device is installed. The INIT routine returns a 
location (DS:DX), which is a pointer to the first 
free byte of memory after the device driver 
(similar to "Keep Process" or "Terminate but Stay 
Resident"). This pointer method can be used to 
delete initialization code that is only needed 
once, saving memory space. 


Block devices are installed the same way and also 
return a first free byte pointer as described 
previously. Additional information is also 
returned (see Chapter 2.6.1 for details on INIT). 


o The number of units is returned. This 
determines logical drive names. If the 
current maximum logical drive letter is F at 
the time of the install call, and the INIT 
routine returns 4 as the number of units, then 
they will have logical names G, H, I and J. 
This mapping is determined by the position of 
the driver in the device list, and by the 
number of units on the device (stored in the 
first byte of the device name field). 


o A pointer to a BPB (BIOS Parameter Block) 


pointer array is also returned. There is one 
table for each unit defined. 
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The format of the BIOS Parameter Block (PBP) is 
as follows: 


bytes per sector 


“BYTE sectors per allocation unit (cluster) 
“WORD number Of reserved sectors 
BYTE number of FATS 

“WORD number of entries in the root directory 


WORD number of sectors in logical image of 
device 


BYTE media descriptor (see below) 


~ WORD number of FAT sectors 


These blocks will be used to build an internal 
bos data structure for each of the units. 

The pointer passed to the DOS from the driver 
points to an array Of n WORD pointers to BPBs, 
where n is the number of units defined. In 
this way, if all units are the same, all of 
the pointers can point to the same BPB, saving 
space. This array must be protected : 
(below the free pointer set by the return) 
since an internal DOS structure will be built 
starting at the byte pointed to by the free 
pointer. The sector size defined must be less 
than or equal to the maximum sector size defined 
at default BIOS INIT time — that is, when the 
BIOS was built. If it isn't, the install will 
fail. 
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o The last thing that INIT of a block device 
must pass back is the media descriptor byte. 
This byte means nothing to MS-DOS, but is 
passed to devices so that they know what 
parameters MS-DOS is currently using for a 
particular drive unit. 


Block devices may take several approaches; they 
may or may not be intelligent. An unintelligent 
device defines a unit (and therefore an internal 
DOS structure) for each possible media drive 
combination. For example, unit 0 = drive 0 
single side, unit 1 = drive 0 double side. For 
this approach, media descriptor bytes do not mean 
anything. An intelligent device allows multiple 
media per unit. In this case, the BPB table 
returned at INIT must define space large enough 
to accommodate the largest possible media 
supported. Intelligent drivers will use the media 
descriptor byte to pass information about what 
media is currently in a unit. 
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Media descriptor bytes are only used to 
distinguish between media of a particular device 
type. Media descriptor bytes have been defined 
for the following media: 


FLOPPY SINGLE/DOUBLE SECTORS MEDIA DESCRIPTOR 


DEVICE SIDED PER TRACK BYTE 
5 1/4" SS 8 FEh 
5 17a" SS 9 FCh 
5 1/a" DS 8 FFh 
5 1/4" DS 9 FDh 
8" Ss 6 FEh 
8" Ss 26 (with 4 FDh 
reserved 
sectors) 
8" DS 8 (with double FEh 
density) 


2.6 FONCTION CALL PARAMETERS 
All strategy routines are called with ES:BX 
pointing to the Request Header. The interrupt 
routines get the pointers to the Request Header 
from the queue that the strategy routines 
store them in. The command code in the Request 
Header tells the driver which function to perform. 
Note: All DWORD pointers are stored offset first, 
then segment. 
2.6.1 INIT 


Command code = 0 


INIT — ES:BX -> 
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a a AA SS OD NOOR Sh SE OO —+ 
! DWORD break address | 
ee ae AE OE Le OE A A EA A A SS SAS OAC Sa Sn eh eI ff 
DWORD pointer to BPB array 
(Not set by character devices) 
pee n + 


The number of units, break address, and BPB 
pointer are set by the driver. On entry, the 
DWORD that is to be set to the BPB array (on block 
devices) points to the character after the '=' 

on the line in CONFIG.SYS that loaded this device. 
This allows drivers to scan the CONFIG.SYS 
invocation line for arguments. 


Note: If there are multiple device drivers ina 
single .COM file, the ending address returned by 
the last INIT called will be the one MS-DOS uses. 
All of the device drivers in a single .COM file 
should return the same ending address. 


2.6.2 MEDIA CHECK 
Command Code = 1 


MEDIA CHECK — ES:BX —> 


rn nn + 
| 13-BYTE Request Header | 
fan na nnn + 
| BYTE media descriptor from DPB | 
fn nn nn + 
| BYTE returned | 
pn nn + 


In addition to setting the status word, the driver 
must set the return byte to one of the following: 


~1 Media has been changed 
0 Don't know if media has been changed 
1 Media has not been changed 


If the driver can return ~1 or 1 (by having a 
door-lock or other interlock mechanism) MS-DOS 
performance is enhanced because MS-DOS does not 
need to reread the FAT for each directory access. 


2.6.3 BUILD BPB (BIOS Parameter Block) 
Command code = 2 


BUILD BPB - ES:BX —-> 


$---- === === 5 + 
| 13-BYTE Request Header a 
fanaa + 
| BYTE media descriptor from DPB | 
+—----------~--------~--------------- + 


DWORD transfer address 

(Points to one sector worth of 
scratch space or first sector 
of FAT depending on the value 
of the NON IBM FORMAT bit) 
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If the NON IBM FORMAT bit of the device is set, 
then the DWORD transfer address points to a one 
sector buffer, which can be used for any purpose. 
Tf the NON IBM FORMAT bit is 0, then this buffer 
contains the first sector of the first FAT and the 
driver must not alter this buffer. 


If IBM compatible format is used (NON IBM FORMAT 
BIT = 0), then the first sector of the first FAT 
must be located at the same sector on all possible 
media. This is because the FAT sector will be 
read BEFORE the media is actually determined. Use 
this mode if all you want is to read the FAT ID 
byte. 


In addition to setting status word, the driver 
must set the Pointer to the BPB on return. 


2.6.4 MEDIA DESCRIPTOR BYTE 


The last two digits of the FAT ID byte are called 
the media descriptor byte. Currently, the media 
descriptor byte has been defined for a few media 
types, including 5-1/4" and 8" standard disks. 


Although these media bytes map directly to FAT ID 
bytes (which are constrained to the 8 values 
F8-FF), media bytes can, in general, be any value 
in the range 0-FF. 
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2.6.5 READ OR WRITE 
Command codes = 3, 4, 8, 9, and 12 


READ or WRITE - ES:BX (Including IOCTL) -> 


anni nen a nee te ee + 
| 13-BYTE Request Header | 
an ne a + 
| BYTE media descriptor from DPB | 
A SS A A yD Se mS a 4+ 
| DWORD transfer address | 
spr + 
| WORD byte/sector count | 
fee nnn + 
WORD starting sector number 
(Ignored on character devices) 
fn nn na a +} 


In addition to setting the status word, the driver 
must set the sector count to the actual number of 
sectors (or bytes) transferred. No error check is 
performed on an IOCTL I/O call. The driver must 
correctly set the return sector (byte) count to 
the actual number of bytes transferred. 


THE FOLLOWING APPLIES TO BLOCK DEVICE DRIVERS: 


Under certain circumstances the BIOS may be asked 
to perform a write operation of 64K bytes, which 
seems to be a "wrap around" of the transfer 
address in the BIOS I/O packet. This request 
arises due to an optimization added to the write 
code in MS-DOS. It will only manifest on user 
writes that are within a sector size of 64K bytes 
on files "growing" past the current EOF. The BIOS 
CAN ignore the balance of the write that "wraps 
around" if it so chooses. However, the returned 
byte/sector count must reflect this. For example, 
a write of 10000H bytes worth of sectors with a 
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transfer address of XXX:1 could ignore the last 
two bytes. A user program can never request an 
I/O of more than FFFFH bytes and cannot wrap 
around (even to 0) in the transfer segment. 
Therefore, in this case, the last two bytes can be 


ignored. 
2.6.6 NON DESTRUCTIVE READ NO WAIT 
Command code = 5 


NON DESTRUCTIVE READ NO WAIT — ES:BX —> 


fn nnn nnn nnn nnn nnn + 
| 13-BYTE Request Header | 
$----------------------------------- + 
| BYTE read from device | 
$--=---------------------------- = ——+ 


If the character device returns busy bit = 0 
(characters in buffer), then the next character 
that would be read is returned. This character is 
not removed from the input buffer (hence the term 
"Non Destructive Read"). Basically, this call 
allows MS-DOS to look ahead one input character. 


2.6.7 STATUS 
Command codes = 6 and 10 
STATUS Calls - ES:BX -> 


omen nn nnn + 


| 13-BYTE Request Header 
fr nn + 
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All the driver must do is set the status word and 
the busy bit as follows: 


oO For output on character devices: If bit 9 (the 
busy bit is 1 on return, a write request (if 
made) would wait for completion of a current 
request. If it is 0, there is no current 
request and a write request (if made) would 
start immediately. 


o For input on character devices with a buffer: 
A return of 1 in the busy bit means a read 
request (if made) would go to the physical 
device. If it is 0 on return, then there are 
characters in the devices buffer and a read 
would return quickly. A return of 0 also 
indicates that the user has typed something. 
MS-DOS assumes that all character devices have 
an input type-ahead buffer. Devices that do 
not have a type-ahead buffer should always 
return busy = 0 so that the DOS will not hang 
waiting for something to get into a buffer 
which doesn't exist. 


2.6.8 FLUSH 
Command codes = 7 and 1l 
FLUSH Calls — ES:BX -> 


t--- 7-5 t 


| 13-BYTE Request Header 


The FLUSH call tells the driver to flush 
(terminate) all pending requests. This call is 
used to flush the input queue on character 
devices. 
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2.7 THE CLOCK DEVICE 


One of the most popular add-on boards is the real 
time clock board. To allow this board to be 
integrated into the system for TIME and DATE, 
there is a special device (determined by the 
attribute word) called the CLOCK device. The 
CLOCK device defines and performs functions like 
any other character device. Most functions will 
be: "set done bit, reset error bit, return." When 
a read or write to this device occurs, exactly 6 
bytes are transferred. The first two bytes are a 
word, which is the count of days since 1~-1-80. 
The third byte is minutes; the fourth, hours; the 
fifth, hundredths of seconds; and the sixth, 
seconds. Reading the CLOCK device gets the date 
and time; writing to it sets the date and time. 


2.8 EXAMPLE OF DEVICE DRIVERS 
All loadable device drivers should not use their 
device name as their filename. (References toa 
filename, if that name is a device driver, will 
always reference the device.). For example, for: 


device = plotdrvr.exe (cr) 


The device name in its header should be 
"PLOTTER _". 
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After receiving an initialize call from MS-DOS, 
loadable device drivers should print this sign-on 
message: 


Driver <DEVICENAME> installed for <hardwarename> 

where: DEVICENAME is the name of the device 
driver file, and hardwarename is the name 
of the physical device. 

For example: 

Driver PLOTTER installed for parallel port. 

To override the standard (default) drivers for 

console, auxilliary I/O list, or clock, you should 

name your loadable device drivers as CON, AUX, 

PRN, or CLOCK, respectively, 

The following examples illustrate a block device 


Griver and a character device driver program. 


2.8.1 BLOCK DEVICE DRIVER 


FOI IIR BLOCK DEVICE JOO RRR 


TITLE 5 1/4" DISK DRIVER FOR SCP DISK-MASTER 


‘This driver is intended by a Hardware OEM to 
;drive up to four 5 

71/4" drives hooked to the Seattle Computer 
sProducts DISK MASTER disk controller. All 
;Standard IBM PC formats are supported. 


2-25 


FALSE EQU 0 
TRUE EQU NOT FALSE 


;The I/O port address of the DISK MASTER 
DISK EQU QEOH 


:DISK+0 

. 1793 Command/Status 
:DISK+1 

, 1793 Track 
sDISK+2 

. 1793 Sector 
:DISK+3 

: 1793 Data 
*DISK+4 

; Aux Command/Status 
sDISK+5 

; Wait Sync 


:Back side select bit 
BACKBIT EQU 04H 
75 1/4" select bit 
SMALBIT EQU 10H 
;Double Density bit 
DDBIT EQU 08H 


;Done bit in status register 
DONEBIT EQU 01H 


;Use table below to select head step speed. 
;Step times for 5" drives 
sare double that shown in the table. 


;Step value 1771 1793 


: 0 6ms 3ms 
: 1 6ms 6ms 
: 2 10ms 10ms 
; 3 20ms 15ms 


STPSPD EQU 1 


NUMERR EQU ERROUT—-ERRIN 
CR EQU ODH 
LF EQU OAH 


CODE SEGMENT 
ASSUME CS:CODE,DS:NOTHING,ES :NOTHING, SS :NOTHING 


? 
; DEVICE HEADER 
; 


DRVDEV LABEL WORD 

-l v -] 

0000 ;IBM format-compatible, Block 
STRATEGY 

DRVS IN 

4 


BEZZEZE 


DRVMAX 
;JUMP TABLE FOR COMMAND HANDLING 
WORD 

DRVS INIT 

MEDIASCHK 

GETSBPB 

CMDERR 

DRVS READ 

EXIT 

EXIT 

EXIT 

DRVSWRIT 

DRVSWRIT 

EXIT 


EXIT 
EXIT 


DRVTBL 


& 
S 


ZZZEESeesyessE 


2-27 


STRATP PROC FAR 


MOV WORD PTR [PTRSAV] ,BX 
MOV WORD PTR [PTRSAV+2] ,ES 


RET ;JUST SAVE REQUEST HEADER 
STRATP ENDP 
H MAIN ENTRY 
CMDLEN = 0 sLENGTH OF THIS COMMAND 
UNIT =] ;SUB UNIT SPECIFIER 
CMDC = 2 :COMMAND CODE 
STATUS = 3 :STATUS 
MEDIA = 13 sMEDIA DESCRIPTOR 
TRANS = 14 TRANSFER ADDRESS 
COUNT = 18 :COUNT OF BLOCKS OR CHARACTERS 
START = 20 ;FIRST BLOCK TO TRANSFER 
DRVSIN: 

PUSH SI 

PUSH AX 

PUSH CX 

PUSH DX 

PUSH DI 

PUSH BP 

PUSH DS 

PUSH ES 

PUSH BX 
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PUSH 
POP 


ASSUME DS:CODE 


BX, [PTRSAV] ;GET POINTER TO I/O PACKET 


AL,BYTE PTR [BX] .UNIT sUNIT CODE 
AH,BYTE PTR [BX].MEDIA ;MEDIA DESCRIP 
CX,WORD PTR [BX] .COUNT ;COUNT 
DX,WORD PTR [BX].START ;START SECTOR 
AX 

AL,BYTE PTR [BX] .CMDC ;Command code 


AL,11 
CMDERRP ;Bad command 
AX,1 72 times command = 


:word table index 
SI,OFFSET DRVIBL 


SI ,AX ;Index into table 
AX 7Get back media 
sand unit 


DI,DWORD PTR [BX] . TRANS 
7ES:DI=TRANSFER ADDRESS 


cS 
DS 


WORD PTR [SI] ;GO DO COMMAND 


CMDERRP : 


POP 
CMDERR: 

MOV 

JMP 


AX sClean stack 


AL,3 ;UNKNOWN COMMAND ERROR 
SHORT ERRSEXIT 


2-29 


ERRSCNT : LDS 


BX, [PTRSAV] 
WORD PTR [BX] .COUNT,CX 
;# OF SUCCESS. I/Os 


. AH,10000001B ;MARK ERROR RETURN 


SHORT ERR1 
FAR 

AH, 000000018 
BX, [PTRSAV] 


WORD PTR [BX] .STATUS,AX 
;MARK OPERATION COMPLETE 


;RESTORE REGS AND RETURN 


-1 


-1,-1,-1,-1 


8 ‘Number of sectors on device 
13 *MAXTIMUM SECTOR 


SUB 
ERRSEXIT: 
;AL has error code 

MOV 

JMP 
EXITP PROC 
EXIT: MOV 
ERRL: LDS 

MOV 

POP 

POP 

POP 

POP 

POP 

POP 

POP 

POP 

POP 

RET 
EXITP ENDP 
CURDRV DB 
TRKTAB DB 
SECCNT DW 
DRVLIM = 
SECLIM = 
HDLIM = 


15. ;MAXIMUM HEAD 


;WARNING - preserve order of drive and curhd! 


DRIVE DB 0 ;PHYSICAL DRIVE CODE 

CURED DB 0 ;CURRENT HEAD 

CURSEC DB 0 ;CURRENT SECTOR 

CURTRK DW 0 ;CURRENT TRACK 

MEDIASCHK : ;Always indicates Don't know 


ASSUME DS:CODE 
TEST AH,00000100B ;TEST IF MEDIA REMOVABLE 


JZ MEDIASEXT 

XOR DI,DI ;SAY I DON'T KNOW 
MEDIASEXT: 

LDS BX, [PTRSAV] 

MOV WORD PTR [BX] .TRANS,DI 

JMP EXIT 
BUILDSBPB : 
ASSUME DS:CODE 

MOV AH,BYTE PTR ES:[DI] ;GET FAT ID BYTE 

CALL GETBP ; TRANSLATE 
SETBPB: LDS BX, [PTRSAV] 

MOV [BX] .MEDIA , AH 

MOV [BX] .COUNT , DI 

MOV [BX] .COUNT+2 ,CS 

JMP EXIT 


BUILDBP : 

ASSUME DS:NOTHING 

;AH is media byte on entry 

;DI points to correct BPB on return 


PUSH AX 

PUSH CX 

PUSH DX 

PUSH BX 

MOV CL,AH ;SAVE MEDIA BYTE 
AND CL, OF8H ;NORMALIZE 


GOODID: 


HAS8: 


HAS1: 


=e se =e te Ne 


s ENTRY : 


CL, OF 8H 7GOOD MEDIA BYTE? 
GOODID 


AH,,OFEH ;DEFAULT TO 8-SECTOR, 
7;SINGLE-SIDED 

AL,1L ;NUMBER OF FAT SECTORS 

BX,64*256+8 ;DIR ENTRIES/SECTOR MAX 

CX, 40*8 7SIZE OF DRIVE 


DX,01*256+1 ;HEAD LIMIT & SEC/ALL UNIT 
DI,OFFSET DRVBPB 
AH,00000010B ;TEST FOR 8 OR 9 SECTOR 


HAS8 ;NZ = HAS 8 SECTORS 

AL s INC NUMBER FAT SECTORS 
BL sINC SECTOR MAX 

CX, 40 s INCREASE SIZE 
AH,00000001B *TEST FOR 1 OR 2 HEADS 
HAS] 7Z = 1 HEAD 

CX,CX sDOUBLE SIZE OF DISK 
BH,112 ; INCREASE # DIR ENTRIES 
DH INC SEC/ALL UNIT 

DL :INC HEAD LIMIT 


BYTE PTR [DI] .2,DH 
BYTE PTR [DI].6,BH 
WORD PTR [DI] .8,CX 
BYTE PTR [DI].10,AH 
BYTE PTR [DI] .11,AL 
BYTE PTR [DI] .13,BL 
BYTE PTR [DI] .15,DL 
BX 
DX 
CX 
AX 


ae a ee A EO ND A A YY DS A PY DS 


DISK I/O HANDLERS 
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DRIVE NUMBER (0-3) 
MEDIA DESCRIPTOR 
SECTOR COUNT 

FIRST SECTOR 

CS 

I = TRANSFER ADDRESS 


BRE e 


Out tt t tt 


ES: 


S 
2 
eI 
. 


IF SUCCESSFUL CARRY FLAG = 0 
ELSE CF=1 AND AL CONTAINS ERROR CODE, 
CX # sectors NOT transferred 


me “Oe Ne Se Me Ne Me Me Ne 


DRV$READ: 

ASSUME DS:CODE 
JICXZ DSKOK 
CALL SETUP 


Jc DSK$IO 

CALL DISKRD 

JMP SHORT DSKS$IO 
DRVSWRIT: 


ASSUME DS :CODE 
JCXZ DSKOK 
CALL SETUP 
JC DSK$IO 
CALL DISKWRT 
ASSUME DS:NOTHING 
DSKSIO: JNC DSKOK 
JMP ERRSCNT 
DSKOK: JMP EXIT 


SETUP : 

ASSUME DS:CODE 

;Input same as above 

3On output 

ES:DI = Trans addr 

DS:BX Points to BPB 

Carry set if error (AL is error code (MS-DOS) ) 
else 


a ee) ee 


{DRIVE] = Drive number (0-3) 
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ma "OG we A Ne 


SEEK: 


[SECCNT] = Sectors to transfer 
(CURSEC] = Sector number of start of I/O 
[CURHD] = Head number of start of I/O 
[CURTRK] = Track # of start of I/O 
All other registers destroyed 
XCHG BX, DI °ES:BX = TRANSFER ADDRESS 
CALL GETBP *DS:DI = PTR TO B.P.B 
MOV SI,CX 
ADD SI,DX 
CMP SI,WORD PTR [DI] .DRVLIM 
*COMPARE AGAINST DRIVE MAX 
JBE INRANGE, 
MOV AL,8 
STC 
RET 
MOV [DRIVE] ,AL 
MOV [SECCNT] ,CX ;SAVE SECTOR COUNT 
XCHG AX,DX ;SET UP LOGICAL SECTOR 
sFOR DIVIDE 
XOR DX,DX 
DIV WORD PTR [DI] .SECLIM 
sDIVIDE BY SECTORS PER 
TRACK 
INC DL 
MOV [CURSEC] ,DL ;SAVE CURRENT SECTOR 
MOV CX,WORD PTR [DI] .HDLIM ;# HEADS 
XOR DX, DX *DIVIDE TRACKS BY HEADS PER CYL 
DIV CX 
MOV {CURHD] ,DL ;SAVE CURRENT HEAD 
MOV [CURTRK] ,AX ;SAVE CURRENT TRACK 
PUSH BX +Xaddr 
PUSH DI ;BPB pointer 
CALL | CHKNEW ;Unload head if change drives 
CALL DRIVESEL 
MOV 


BL, [DRIVE] 
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SEEKERR: 


POP 
POP 


BH,BH 


yBX drive index 


BX,OFFSET TRKTAB ;Get current track 
AX, [CURTRK] 


DL,AL 
AL,DS: [BX] 
DISK+1,AL 
AL,DL 
SEEKRET 
BH,2 
AL,-1 
NOHOME 


HOME 
SEEKERR 


AL,DL 
DISK+3,AL 


:Save desired track 
;Make desired track current 
:Tell Controller current track 
sAt correct track? 
;Done if yes 
;Seek retry count 
:Position Known? 
sI£ not home head 


‘Desired track 


AL,1CH+STPSPD ;Seek 


DCOM 
AL, 98H 
SEEKRET 
SEEKERR 
BH 
TRYSK 


BL, [DRIVE] 
BH, BH 


;Accept not rdy, seek, & CRC errors 


s;No retries if not ready 


*BX drive index 


BX,OFFSET TRKTAB ;Get current track 
BYTE PTR DS: [BX] ,-1 


GETERRCD 


sMake current track 
sunknown 


CX, [SECCNT}] ;Nothing transferred 


BX 
DI 


;BPB pointer 
+ Xaddr 


2-35 


errors 


SEEKRET : 


BX +BPB pointer 
DI :Xaddr 


es es a Oa a 


ASSUME DS:CODE 


CX, [SECCNT] 


PRESET 

BX 

BL,1O ;Retry count 
DX,DISK+3 ;Data port 


AL, 80H ;Read command 
;Disable for 1793 
DISK,AL ;Output read command 


BP,DI ;Save address for retry 
SHORT RLOOPENTRY 


AL,DISK+5 ;Wait for DRO or INTRQ 
AL,DX sRead data 


:Ints OK now 


RDPOP 20k 
DI,BP ;Get back transfer 
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CMP AL, LOH ;Record not found? 
JNZ GOT_CODE ;No 


MOV AL,1 ;Map it 
GOT_CODE: 
CALL GETERRCD 
POP BX 
RET 
RDPOP : 
POP BX 
LOOP RDLP 
CLC 
RET 
H WRITE 
7 
DISKWRT : 


ASSUME DS:CODE 


PUSH ES 
POP DS 
ASSUME DS:NOTHING 
WRLP: 
CALL PRESET 
PUSH BX 
MOV BL,10 ;Retry count 
MOV DX,DISK+3 ;Data port 
WRAGN : 
MOV AL,QAOH ;Write command 
CLI ;Disable for 1793 
OUT DISK,AL ;Output write command 
MOV BP,SI ;Save address for retry 
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WRLOOP : 


WRPOP : 


PRESET's 
ASSUME 


IN AL,DISK+5 

SHR AL,1 

LODSB :Get data 

OUT DX, AL Write data 

JNC WRLOOP 

STI :Ints OK now 

DEC SI 

CALL GETSTAT 

AND AL,OFCH 

JZ WRPOP 3Ok 

MOV SI,BP ;Get back transfer 
DEC BL 

JNZ WRAGN 

CALL GETERRCD 

POP BX 

RET 

POP BX 

LOOP WRLP 

CLC 

RET 

DS :NOTHING 

MOV AL, [CURSEC] 

CMP AL,CS: [BX] .SECLIM 

JBE GOTSEC 

MOV DH, (CURHD] 

INC DH 

CMP DH,CS: (BX] .HDLIM 

JB SETHEAD ;Select new head 
CALL STEP *Go on to next track 
XOR DH,DH sSelect head zero 


GOTSEC: 


STEP 
ASSUME 


HOMERR: 


MOV {CURHD] ,DH 

CALL DRIVESEL 

MOV AL,1 *First sector 

MOV [CURSEC] , AL ;Reset CURSEC 

OUT DISK+2,AL ;Tell controller which sector 

INC {CURSEC] ;We go on to next sector 

RET 

DS :NOTHING 

MOV AL, 58H+STPSPD ; 

CALL DCOM ;Step in w/ update, no verify 

PUSH BX H . 

MOV BL, [DRIVE] 

XOR BH, BH :BX drive index 

ADD BX,OFFSET TRKTAB ;Get current track 
' INC BYTE PTR CS:[BX] ;Next track 

POP BX 

RET 

DS :NOTHING 

MOV BL,3 

MOV AL,OCH+STPSPD ;Restore with verify 

CALL DCOM 

AND AL,98H 

JZ RET3 

Js HOMERR ;No retries if not ready 

PUSH AX ;Save real error code 

MOV AL, 53H+STPSPD ; 

CALL DCOM ;Step in w/ update no verify 

DEC BL : 

POP AX 7Get back real error code 

JNZ TRYHOM 

STC 
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RET3: RET 


CHKNEW: 
ASSUME DS:NOTHING 
MOV AL, [DRIVE] ;Get disk drive number 
MOV AH, AL 
XCHG AL, [CURDRV] ;Make new drive current. 
CMP AL,AH ;Changing drives? 
JZ RET1L ;No 
; If changing drives, unload head so the head load 
;delay one-shot will fire again. Do it by seeking 
sto the same track with the H bit reset. 


t 


IN AL,DISK+l ;Get current track number 
OUT DISK+3,AL  ;Make it the track to seek 
MOV AL, 10H :Seek and unload head 


DCOM: 
ASSUME DS:NOTHING 


PUSH AX 
AAM ;Delay 10 microseconds 
POP AX 
GETSTAT: 
IN AL,DISK+4 
TEST AL, DONEBIT 
JZ GETSTAT 
IN AL, DISK 
RETL: RET 
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DRIVESEL: 
ASSUME DS:NOTHING 
;Select the drive based on current info 
;Only AL altered 
MOV AL, [DRIVE] 


OR AL,SMALBIT + DDBIT ;5 1/4" IBM PC disks 
CMP [CURHD] ,0 
JZ GOTHEAD 
OR AL,BACKBIT ;Select side 1 
GOTHEAD : 
OUT DISK+4,AL ;Select drive and side 
RET 
GETERRCD : 
ASSUME DS:NOTHING 
PUSH CX 
PUSH ES 
PUSH DI 
PUSH cs 
POP ES ;Make ES the local segment 


MOV CS: (LSTERR] ,AL ;Terminate with error code 
MOV CX,NUMERR ;# error conditions 

MOV DI,OFFSET ERRIN ;Point to error cond 
REPNE SCASB 

MOV AL,NUMERR-1(DI] ;Get translation 


STC 3;Flag error condition 
POP DI 

POP ES 

POP CX 

RET sand return 
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g RRKERRKEKRK ERR EKER RRR EERE ERERERERERERERERRRRERERK 


:BPB FOR AN IBM FLOPPY DISK, VARIOUS PARAMETERS ARE 
*PATCHED BY GETBP TO REFLECT THE TYPE OF MEDIA 

; INSERTED 
‘This is a nine sector single side BPB 


DRVBEPB : 


INITAB 


ERRIN: 


LSTERR 


ERROUT': 


;Physical sector size in bytes 
7Sectors/allocation unit 
:Reserved sectors for DOS 

:# Of allocation tables 
;Number directory entries 
;Number 512—byte sectors 


11111100B ;Media descriptor 


sNumber of FAT sectors 
sSector limit 
sHead limit 


:Up to four units 


;DISK ERRORS RETURNED FROM 1793 CONTROLLER 


:NO RESPONSE 

;Write protect 

sWrite Fault 

;SEEK error 

7;CRC error 

;Mapped from 10H 

:(cecord not found) on READ 
sALL OTHER ERRORS 


;RETURNED ERROR CODES FOR ABOVE 


DW 512 

DB l 

DW 1 

DB 2 

DW 64 

DW 9* 40 
DB 

DW 2 

DW 9 

DW 1 

DW DRVBPB 
DW DRVBPB 
DW DRVBPB 
DW DRVBPB 
DB 80H 
DB 40H 
DB 20H 
DB 10H 
DB 8 

DB l 

DB 0 

DB 2 

DB 0 


7NO RESPONSE. 
;WRITE ATTEMPT 
7;ON WRITE-PROTECT DISK 
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DB OAH ;WRITE FAULT 


DB 6 7;SEEK FAILURE 

DB 4 7BAD CRC 

DB 8 ;SECTOR NOT FOUND 

DB 12 ;GENERAL ERROR 
DRVS INIT: 


Determine # physical drives from CONFIG.SYS 


~e me Ne 


ASSUME DS:CODE 


PUSH DS 

LDS SI, [PTRSAV] 
ASSUME DS:NOTHING 

LDS SI,DWORD PTR [SI.COUNT] 

;DS:SI POINTS TO CONFIG.SYS 

SCAN LOOP: 

CALL SCAN SWITCH 

MOVs AL, CL 

OR AL, AL 

JZ SCAN4 

CMP Ss, "s" 

JZ SCAN4 


WERROR: POP DS 
ASSUME DS:CODE 


INT 21H 

XOR AX, AX 

PUSH AX ;No units 

JMP SHORT ABORT 
BADNDRV : 

POP DS 


MOV DX,OFFSET ERRMSGL 
JMP WERROR2 
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SCAN 4: 
ASSUME 
:BX is 


ASSUME 


ABORT: 
ASSUME 


=e se Se 


DS :NOTHING 

number of floppies 

OR BX,BX 

JZ BADNDRV ;User error 

CMP BX,4 

JA BADNDRV ;User error 

POP DS 

DS : CODE 

PUSH BX :Save unit count 
LDS BX, [PTRSAV] 

DS :NOTHING 

POP AX 

MOV BYTE PTR [BX].MEDIA,AL ;Unit count 
MOV [DRVMAX] , AL 


MOV WORD PTR [BX]. TRANS, OFFSET DRVSINIT 
;SET BREAK ADDRESS 
MOV [BX] . TRANS+2,CS 
MOV WORD PTR [BX] .COUNT,OFFSET INI'TAB 
;SET POINTER TO BPB ARRAY 
MOV [BX] .COUNT+-2,CS 
JMP EXIT 


PUT SWITCH IN CL, VALUE IN BX 


SCAN SWITCH: 


XOR BX, BX 
MOV CX,BX 


LODSB 

CMP AL, 10 

JZ NUMRET 

CMP AL, woe 

JZ GOT_SWITCH 

CMP AL ; LT 

INZ SCAN SWITCH 
GOT SWITCH: 

CMP BYTE PTR [SI+1],":" 

JNZ TERROR 

LODSB 
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OR AL, 20H s CONVERT TO LOWER CASE 
MOV CL,AL : GET SWITCH 
LODSB : SKIP ":" 


GET NUMBER POINTED TO BY [SI] 
WIPES OUT AX,DX ONLY BX RETURNS NUMBER 


GETNUM1 : LODSB 


se te 8 Me Ne 


SUB AL, "0" 
JB CHKRET 
CMP AL,9 
JA CHKRET 
CBW 
XCHG AX,BX 
MOV DX, 10 
MUL DX 
ADD BX, AX 
JMP GETNUML 
CHKRET: ADD AL, "0" 
CMP AL," " 
JBE NUMRET 
CMP AL,"-" 
JZ NUMRET 
CMP AL, myn 
JZ NUMRET 
TERROR: 
POP DS ; GET RID OF RETURN ADDRESS 
JMP WERROR 
NUMRET: DEC SI 
RET 
ERRMSG] DB "SMLDRV: Bad number of drives" 
DB 13,10,"5" 
ERRMSG2 DB "SMLDRV: Invalid parameter" 
DB 13,10,"$" 
CODE ENDS 
END 


2.8.2 CHARACTER DEVICE DRIVER 


The following program illustrates a character 
device driver program. 


KKEKEKEREKEEKERERD CHARACTER DEVICES EKEEEAKKKEEKKKKK 


TITLE VI52 CONSOLE FOR 2.0 


CR=13 7CARRIAGE RETURN 

BACKSP=8 7 BACKSPACE 

ESC=1BH 

BRKADR=6CH ;006C BREAK VECTOR 
ADDRESS 

ASNMAX=200 7SIZE OF KEY ASSIGNMENT 
BUFFER 


CODE SEGMENT BYTE 


ASSUME CS:CODE,DS :NOTHING, ES :NOTHING 


Se eee i A A a A A Re a PS A A uD 


? C ON — CONSOLE DEVICE DRIVER 

CONDEV : ;HEADER FOR DEVICE "CON" 
DW pd. 
DW 1000000000010011B ;CON IN AND OUT 
DW STRATEGY 
DW ENTRY 
DB "CON : 
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CMDTABL 


EYEREZREREs 


CUU 7CULSOr up 

CUD scursor down 

CUF ;cursor forward 

CUB ;cursor back 

CUH ;cursor position 

ED ;erase display 

EL erase line 

CUP ;Cursor position 
PSCP ;Save cursor position 
PRCP ;restore cursor position 
RM ;reset mode 


SM ;set mode 
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CMDLEN = 
UNIT = 
CMD = 
STATUS = 
MEDIA = 
TRANS = 
QOUNT = 
STARE = 
PTRSAV DD 
STRATP PROC 
STRATEGY : 
MOV 
MOY 
RET 
STRATP ENDP 
ENTRY : 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
LDS 
MOV 


0 ?;LENGTH OF THIS COMMAND 

1 ;SUE UNIT SPECIFIER 

2 ;QOMMAND CODE 

3 ; STATUS 

13 7MEDIA DESCRIPTOR 

14 7 TRANSFER ADDRESS 

18 ;COUNT OF BLOCKS OR CHARACTERS 
20 ;FIRST BLOCK TO TRANSFER 

0 

FAR 


WORD PTR CS: [PTRSAV] ,BX 
WORD PTR CS: [PTRSAV+2] ,ES 


BX,CS: [PTRSAV] ;PTR TO I/O PACKET 


CX,WORD PTR DS: [BX] .COUNT 


USSEXIT: 
MOV 
JMP 


CMDERR: 
MOV 


ERRSEXIT: 
MOV 
JMP 


ee ee re oer nee ee 


AL,BYTE PTR DS: [BX] .CMD 
SI,OFFSET CONTBL 

SI ,AX 

SI ,AX 

AL, 11 

CMDERR 

DI,DWORD PTR DS: [BX] . TRANS 


cS 
DS 


DS :CODE 


WORD PTR [SI] ;GO DO COMMAND 


EXIT — ALL ROUTINES RETURN THROUGH THIS PATH 


;DEVICE BUSY EXIT 
AH ,00000011B 
SHORT ERR1 


AL,3 ; UNKNOWN COMMAND ERROR 


AH,10000001B ;MARK ERROR RETURN 
SHORT ERRL 
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EXITP 


EXIT: 
ERR]: 


UW ~0 ~e we = 


PROC FAR 


MOV AH ,00000001B 


LDS BX,CS: [PTRSAV] 

MOV WORD PTR [BX] .STATUS,AX ;MARK 
s;OPERATION COMPLETE 

POP BX 

POP ES 

POP DS 

POP BP 

POP DI 

POP DX 

POP CX 

POP AX 

POP SI 

RET ;RESTORE REGS AND RETURN 

ENDP 


BREAK KEY HANDLING 


MOV CS:ALTAH,3 ;INDICATE BREAK KEY SET 


: ITRET 


WARNING ~ Variables are very order dependent, 
so be careful when adding new ones! 


; 0 = WRAP, 1 = NO WRAP 


| aoe 


Oo 
w 
eoocoynwnse 
it) 


;Special key handling 
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CHROUT - WRITE OUT CHAR IN AL USING CURRENT ATTRIBUTE 


ATTRW LABEL WORD 


ATTR DB 00000111B ;CHARACTER ATTRIBUTE 
BPAGE DB 0 ;BASE PAGE 
base dw 0b800h 
chrout: cmp al,13 

jnz trylf 

MOV [col] ,0 

jmp short setit 
trylf: cmp al,10 

jz LE 

cmp al,7 

nz tryback 
toroms: 

Mov bx, [attrw] 

and b1,7 

mov ah,14 

int 10h 
ret5: ret 
tryback : 

cmp al,8 

jnz outchr 

cmp [col] ,0 

jz ret5 

dec [col] 

jmp short setit 
outchr: 

Mov bx, [attrw] 

mov cx,l 

mov ah,9 

int 10h 


inc 


jbe 


jz 

dec 

ret 
outchrl1: 


lf: inc 


jb 
mov 
call 


setit: mov 
mov 
XOr 
mov 
int 
ret 


scroll: call 
cmp 
4z 
cmp 
jz 
MOV 
jmp 

myscroll: 
mov 
MOV 


[col] 

al, [col] 
al, [maxcol] 
setit 
{wrap] ,0 
outchr1 
{col] 


[col] ,0 
[row] 
[row] ,24 
setit 
[row] ,23 
scroll 


dh , row 
d1,col 
bh, bh 
ah,2 
10h 


getmod 
al,2 
myscroll 
al,3 
myscroll 
al,10 
torom 


bh, [attr] 
bl,' ' 
bp, 80 
ax, [base] 
es ,ax 

ds ,ax 
di,di 
si,160 


ono 


Mov cx, 23*80 


cld 
cmp ax, 0b800h 
jz colorcard 
rep movsw 
mov ax, bx 
mov cx, bp 
rep stosw 
sret: push cs 
pop ds 
ret 
colorcard: 
mov dx, 3dah 
wait2: in al,dx 
test al,8 
jz wait2 
mov al,2c 
mov dx, 3d8h 
out dx,al sturn off video 
rep movsw 
mov ax, bx 
mov cx, bp 
rep stosw 


Mov al,29h 
mov dx, 3d8h 


out dx,al ;turn on video 
jmp sret 
GETMOD: MOV AH,15 
INT 16 sget colum information 
MOV BPAGE , BH 
DEC AH 
MOV WORD PTR MODE,AX 
RET 


CONSOLE READ ROUTINE 
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CONSLOOP : 
PUSH CX ;SAVE COUNT 
CALL CHRIN ;GET CHAR IN AL 
POP CX 
STOSB ;STORE CHAR AT ES;:DI 
LOOP CONSLOOP 
CONSEXIT: 
JMP EXIT 
: INPUT SINGLE CHAR INTO AL 


CHRIN: XOR AX, AX 


XCHG AL,ALTAH ;GET CHARACTER & ZERO ALTAH 


OR AL, AL 
JNZ KEYRET 
INAGN: XOR AH, AH 
INT 22 
ALTO: 
OR AX, AX ;Check for non-key after BREAK 
JZ INAGN 
OR AL, AL ;SPECIAL CASE? 
JNZ KFYRET 


MOV ALTAH,AH ;STORE SPECIAL KEY 


KEYBOARD NON DESTRUCTIVE READ, NO WAIT 


a a 


CONSRDND: 
MOV AL, [ALTAH] 
OR AL,AL 
JNZ RDEXIT 


RD1: MOV AH,1 
INT 22 
JZ CONBUS 
OR AX,AX 
JNZ RDEXIT 
MOV AH,0 
INT .22 
JMP CONSRDND 
RDEXIT: LDS BX, [PTRSAV] 
MOV (BX] MEDIA, AL 
EXVEC: JMP EXIT 
CONBUS: JMP BUSSEXIT 
: KEYBOARD FLUSH ROUTINE 
CONSFLSH: 
MOV {ALTAH],0 ;Clear out holding buffer 
PUSH DS 
XOR BP,BP 
MOV DS ,BP ;Select segment 0 
MOV DS:BYTE PTR 41AH,1EH ;Reset KB queue head 
pointer 
MOV DS:BYTE PTR 41CH,1EH ;Reset tail pointer 
POP DS 
JMP EXVEC 


me Ne se Ne 


CONSWRIT: 


JCXZ 
PUSH 
MOV 
XOR 
INT 


CONSOLE WRITE ROUTINE 


EXVEC 

CX 

AH,3 7;SET CURRENT CURSOR POSITION 
BX,BX 

16 
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MOV WORD PTR [COL] ,DX 


POP CX 
CONSLP: MOV AL,ES: [DI] ;GET CHAR 
INC DI 


CALL OUTC ;OUTPUT CHAR 
LOOP CONSLP ;REPEAT UNTIL ALL THROUGH 
JMP EXVEC 


COUT: STI 
PUSH DS 
PUSH cs 
POP DS 
CALL  OUTC 
POP DS 
IRET 

OUTC: PUSH AX 
PUSH CX 
PUSH DX 
PUSH SI 
PUSH DI 
PUSH ES 
PUSH BP 
CALL . VIDEO 
POP BP 
POP ES 
POP DI 
POP SI 
POP DX 
POP CX 
POP AX 
RET 


; 
; OUTPUT SINGLE CHAR IN AL TO VIDEO DEVICE 


VIDEO: MOV SI ,OFFSET STATE 


2-56 


Sl: CMP AL,ESC  ;ESCAPE SEQUENCE? 
JNZ S1B 
MOV WORD PTR [SI] ,OFFSET S2 
RET 


S1B: CALL CHROUT 
S1A: MOV WORD PTR [STATE] ,OFFSET Sl 


RET 

$2: PUSH AX 
CALL GETMOD 
POP AX 


MOV BX,OFFSET CMDTABL-3 
S7A: ADD BX,3 


CMP BYTE PTR [BX] ,0 
JZ S1A 

CMP BYTE PTR [BX] ,AL 
JNZ S7A 


JMP WORD PTR [BX+1] 


MOVCUR: CMP BYTE PTR [BX] ,AH 
JZ SETCUR 
ADD BYTE PTR [BX] ,AL 
SETCUR: MOV DX,WORD PTR COL 
XOR BX, BX 


MOV AH,2 
INT 16 
JMP S1A 
CUP: MOV WORD PTR [SI] ,OFFSET CUP1 
RET 


CUP1: SUB AL, 32 
MOV BYTE PTR [ROW] ,AL 
MOV WORD PTR [SI] ,OFFSET CUP2 


CUP2: SUB AL, 32 
MOV BYTE PTR [COL] ,AL 
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JMP SETCUR 


SM: MOV WORD PTR [SI] ,OFFSET S1A 


CUF: MOV AH ,MAXCOL 
MOV AL,1 

CUF1: MOV BX,OFFSET COL 
JMP MOVCUR 


CUB: MOV AX, OOFFH 
JMP CUFL 


CUU: MOV AX, OOFFH 
CUU1: MOV BX,OFFSET ROW 
JMP MOVCUR 


CUD: MOV AX, 23*2 56+1 
JMP CUU1 


PSCP: MOV AX,WORD PTR COL 
MOV SAVCR,AX 
JMP SETCUR 


PRCP: MOV AX, SAVCR 
MOV WORD PTR COL,AX 
JMP SETCUR 


ED: CMP BYTE PTR [ROW] ,24 
JAE ELL ; 


MOV CX,WORD PTR COL 
MOV DH, 24 
JMP ERASE 


EL1: MOV BYTE PTR [COL] ,0 
EL: MOV CX,WORD PIR [COL] 


RM: MOV WORD PTR [SI] ,OFFSET RM1 
RET 
RM1: XOR CX,CX 
MOV CH,24 
JMP EL2 
CONSINIT: 
int 1lh 


and al,00110000b 
cmp al,00110000b 


jnz iscolor 

mov [base] ,Ob000h ;look for bw card 
iscolor: 

cmp al,00010000b ;look for 40 col mode 

ja setbrk 

mov [mode] ,0 

mov [maxcol1} , 39 


setbrk: 
XOR BX,BX 
MOV DS ,BX 
MOV BX, BRKADR 
MOV WORD PTR [BX] ,OFFSET BREAK 
MOV WORD PTR [BX+2],CS 


MOV BX, 29H*4 

MOV WORD PTR [BX] ,OFFSET COUT 

MOV WORD PTR [BX+2] ,CS 

LDS BX,CS: [PTRSAV] 

MOV WORD PTR [BX]. TRANS,OFFSET CONSINIT 


;SET BREAK ADDRESS 


MOV [BX] . TRANS+2,CS 
JMP EXIT 

CODE ENDS 
END 


3. MS-DOS TECHNICAL INFORMATION 


3.1 MS-DOS INITIALIZATION 


MS-DOS initialization consists of several steps. 
Typically, a ROM (Read Only Memory) bootstrap 
obtains control, and then reads the boot sector 
off the disk. The boot sector then reads the 
following files: 


o I10.SYS 
o MSDOS.SYS 


Once these files are read, the boot process 


begins. 


3.2 THE COMMAND PROCESSOR 


The command processor supplied with MS-DOS (file 
COMMAND.COM) consists of three parts: 


1. A resident part resides in memory. This part 
contains routines to process Interrupts 23H 
(ALT-C Exit Address) and 24H (Fatal Error 
Abort Address), as well as a routine to reload 
the transient part, if needed. All standard 
MS-DOS error handling is done within this part 
of COMMAND.COM. This includes displaying 
error messages and processing the Abort, 
Retry, or Ignore messages. 
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2. An initialization part is given control during 
initialization; it contains the AUTOEXEC file 
processor setup routine. The initialization 
part determines the segment address at which 
programs can be loaded. It is overlaid by the 
first program COMMAND.COM loads because it is 
no longer needed. 


3. A transient part is loaded’ at the high end of 
memory. This part contains all of the 
internal command processors and the batch file 
processor. The transient part of the command 
processor produces the system prompt (such as 

’ A>), reads the command from keyboard (or batch 
file) and causes it to be executed. For 
external commands, this part builds a command 
line and issues the EXEC system call (Function 
Request 4BH) to load and transfer control to 
the program. 


3.3 MS-DOS DISK ALLOCATION 
The MS-DOS area is formatted as follows: 


o Reserved area — variable size 


o First copy of file allocation table -- variable 
size 


o Second copy of file allocation table -—- 
variable size (optional) 


o Additional copies of file allocation table — 
variable size (optional) 


o Root directory — variable size 


© File data area 
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Allocation of space for a file in the data area is 
not pre-allocated. The space is allocated one 
cluster at a time. A cluster (or allocation unit) 
consists of one or more consecutive sectors; all 
of the clusters for a file are "chained" together 
in the File Allocation Table (FAT). (Refer to 
Chapter 3.5.) There is usually a second copy of 
the FAT kept, for data integrity. Should the disk 
develop a bad sector in the middle of the first 
FAT, the second can be used. This avoids loss of 
data due to an unusable disk. 


3.4 MS-DOS DISK DIRECTORY 


FORMAT builds the root directory for all disks. 
The directory's location on disk and the maximum 
number of entries are dependent on the media. 


Since directories other than the root directory 
are regarded as files by MS-DOS, there is no limit 
to the number of files they may contain. 


All directory entries are 32 bytes in length, and 
are in the following format (note that byte 
offsets are in hexadecimal): 


0-7 Filename. Eight characters, left aligned 
and padded, if necessary, with blanks. 
The first byte of this field indicates the 
file status as follows: 


OOH The directory entry has never been 
used. This is used to limit the 
length of directory searches, for 
performance reasons. 
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8-0A 


0B 


2EH 


ER 


The entry is for a directory. If 
the second byte is also 2EH, then 
the cluster field contains the 
cluster number of this directory's 
parent directory (0000H if the 
parent directory is the root 
directory). Otherwise, bytes 01H 
through OAH are all spaces, and the 
cluster field contains the cluster 
number of this directory. 


The file was used, but it has been 
erased. 


Any other character is the first character 
of a filename. 


Filename extension. 


File attribute. The attribute byte is 
mapped as follows (values are in 
hexadecima1]) : 


01 


02 


04 


File is marked read-only. An attempt 
to open the file for writing using 
the Open File system call (Function 
Request 3DH) results in an error code 
being returned. This value can be 
used along with other values below. 
Attempts to delete the file with the 
Delete File system call (13H) or 
Delete a Directory Entry (41H) will 
also fail. 


Hidden file. The file is excluded 
from normal directory searches. 


System file. The file is excluded 
from normal directory searches. 
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0Cc-15 


16-17 


08 


10 


20 


The entry contains the volume label 
in the first 11 bytes. The entry 
contains no other usable information 
(except date and time of creation), 
and may exist only in the root 
directory. 


The entry defines a sub-directory, 
and is excluded from normal directory 
searches, 


Archive bit. The bit is set to "on" 
whenever the file has been written to 
and closed. 


Note: The system files (IO.SYS and 
MSDOS.SYS) are marked as read-only, 
hidden, and system files. Files can 
be marked hidden when they are 
created. Also, the read-only, hidden, 
system, and archive attributes may be 
changed through the Change Attributes 
system call (Function Request 43H). 


Reserved. 


Time the file was created or last updated. 
The hour, minutes, and seconds are mapped 


into two bytes as follows: 


Offset 17H 


Jol a] a] A] aA [ M | M|M | 
7 4 3 2 0 


Offset 16H 


|M|m|[mM|[s|[s{s|s|s| 
7 5 4 0 
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where: 


H is the binary number of hours (0-23) 


M is the binary number of minutes 
(0-59) 

S is the binary number of two-second 
increments 


Date the file was created or last updated. 
The year, month, and day are mapped into 
two bytes as follows: 


Offset 19H 
ly}y|ylylyly|y|[m| 
7 1 0 


Offset 18H 
|mM|mM|{[M|[D|[D|pd|pD|{D| 
7 5 4 0 


where: 

Y is 0-119 (1980-2099) 
M is 1-12 

D is 1-31 


Starting cluster; the cluster number of 
the first cluster in the file. 


The first cluster for data space on all 
disks is cluster 002. 


The cluster number is stored with the 
least significant byte first. 


Note: Refer to Chapter 3.5.1, for details 
about converting cluster numbers to 
logical sector numbers. 


1c-lF File size in bytes. The first word of 
this four-byte field is the low-order part 
of the size. 


3.5 FILE ALLOCATION TABLE (FAT) 


The following information is included for system 
programmers who wish to write installable device 
drivers. This section explains how MS-DOS uses 
the File Allocation Table to convert the clusters 
of a file to logical sector numbers. The driver 
is then responsible for locating the logical 
sector on disk. Programs must use the MS-DOS file 
management function calls for accessing files; 
programs that access the FAT are not guaranteed to 
be upwardly compatible with future releases of 
MS-DOS. 


The File Allocation Table is an array of 12-bit 
entries (1-1/2 bytes) for each cluster on the 
disk. The first two FAT entries map a portion of 
the directory; these FAT entries indicate the size 
and format of the disk. 


The second and third bytes currently always 
contain FFH. 


The third FAT entry, which starts at byte offset 
4, begins the mapping of the data area (cluster 
002). Files in the data area are not always 
written sequentially on the disk. The data area 
is allocated one cluster at a time, skipping over 
clusters already allocated. The first free 
cluster found will be the next cluster allocated, 
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regardless of its physical location on the disk. 
This permits the most efficient utilization of 
disk space because clusters made available by 
erasing files can be allocated for new files. 


Each FAT entry contains three hexadecimal 
characters: 


000 If the cluster is unused and available. 


FF7 The cluster has a bad sector in it. 
MS-DOS will not allocate such a cluster. 
CHKDSK counts the number of bad clusters 
for its report. These bad clusters are 
not part of any allocation chain. 


FF8-FFF Indicates the last cluster of a file. 


XXX Any other characters that are the 
cluster number of the next cluster in 
the file. The cluster number of the 
first cluster in the file is kept in 
the file's directory entry. 


The File Allocation Table always begins on the 
first section after the reserved sectors. If the 
FAT is larger than one sector, the sectors are 
contiguous. Two copies of the FAT are usually 
written for data integrity. The FAT is read into 
one of the MS-DOS buffers whenever needed (open, 
read, write, etc.). For performance reasons, this 
buffer is given a high priority to keep it in 
memory as long as possible. 


3-8 


3.5.1 USING THE FILE ALLOCATION TABLE 


Use the directory entry to find the starting 
cluster of the file. Next, to locate each 
subsequent cluster of the file: 


1. 


Multiply the cluster number just used by 1-1/2 
(each FAT entry is 1-1/2 bytes long). 


The whole part of the product is an offset 
into the FAT, pointing to the entry that maps 
the cluster just used. That entry contains 
the cluster number of the next cluster of the 
file. 


Use a MOV instruction to move the word at the 
calculated FAT offset into a register. 


If the last cluster used was an even number, 
keep the low-order 12 bits of the register by 
ANDing it with FFF; otherwise, keep the high- 
order 12 bits by shifting the register right 4 
bits with a SHR instruction. 


If the resultant 12 bits are FF8H to FFFH the 
file contains no more clusters. Otherwise, 
the 12 bits contain the cluster number of the 
next cluster in the file. 


a 


To convert the cluster to a logical sector number 
(relative sector, such as that used by THESE TUDES 
25H and 26H and by DEBUG): 


1. Subtract 2 from the cluster number. 


2. Multiply the result by the number of sectors 
per cluster. 


3. Add to this result the logical sector number 
of the beginning of the data area. 


3.6 MS-DOS STANDARD DISK FORMATS 


On an MS-DOS disk, the clusters are arranged on 
disk to minimize head movement for multi-sided 
media. All of the space on a track (or cylinder) 
is allocated before moving on to the next track. 
This is accomplished by using the sequential 
sectors on the lowest-numbered head, then all the 
sectors on the next head, and so on until all 
sectors on all heads of the track are used. The 
next sector to be used will be sector 1 on head 0 
of the next track. 
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4. MS-DOS CONTROL BLOCKS AND WORK AREAS 


4.1° MS-DOS PROGRAM SEGMENT 


When an external command is typed, or when you 
execute a program through the EXEC system call, 
MS~DOS determines the lowest available free memory 
address to use as the start of the program. This 
area is called the Program Segment. 


The first 256 bytes of the Program Segment are set 
up by the EXEC system call for the program being 
loaded into memory. The program is then loaded 
following this block. An .EXE file with minalloc 
and maxalloc both set to zero is loaded as high as 
possible. 


At offset 0 within the Program Segment, MS-DOS 
builds the Program Segment Prefix control block. 
The program returns from EXEC by one of four 
methods: 


1. A long jump to offset 0 in the Program Segment 
Prefix 


2. By issuing an INT 20H with CS:0 pointing at 
the PSP 


3. By issuing an INT 21H with register AH=0 with 
CS:0 pointing at the PSPS, or 4CH and no 
restrictions on CS 


4. By a long call to location 50H in the Program 
Segment Prefix with AH=0 or Function Request 
4CH 


Note: It is the responsibility of all programs to 
ensure that the CS register contains the segment 
address of the Program Segment Prefix when 
terminating via any of these methods, except 
Function Request 4CH. For this reason, using 
Function Request 4CH is the preferred method. 


All four methods result in transferring control to 
the program that issued the EXEC. During this 
returning process, Interrupts 22H, 23H, and 24H 
(Terminate Address, ALT-C Exit Address, and Fatal 
Error Abort Address) addresses are restored from 
the values saved in the Program Segment Prefix of 
the terminating program. Control is then given to 
the terminate address. If this is a program 
returning to COMMAND.COM, control transfers to its 
resident portion. If a batch file was in process, 
it is continued; otherwise, COMMAND.COM performs a 
checksum on the transient part, reloads it if 
necessary, then issues the system prompt and waits 
for you to type the next command. 


When a program receives control, the following 
conditions are in effect: 


l. For all programs: 
The segment address of the passed environment 
is contained at offset 2CH in the Program 
Segment Prefix. 


The environment is a series of ASCII strings 
(totaling less than 32K) in the form: 


NAME=par ameter 


Each string is terminated by a byte of zeros, 
and the set of strings is terminated by 
another byte of zeros. The environment built 
by the command processor contains at least a 
COMSPEC= string (the parameters on COMSPEC 
define the path used by MS-DOS to locate 
COMMAND.COM on disk). The last PATH and 
PROMPT commands issued will also be in the 
environment, along with any environment 
strings defined with the MS-DOS SET command. 


The environment that is passed is a copy of 
the invoking process environment. If your 
application uses a "keep process" concept, you 
should be aware that the copy of the 
environment passed to you is static. That is, 
it will not change even if subsequent SET, 
PATH, or PROMPT commands are issued. 


Offset 50H in the Program Segment Prefix 
contains code to call the MS-DOS function 
dispatcher. By placing the desired function 
request number in AH, a program can issue a 
far call to offset 50H to invoke an MS-DOS 
function, rather than issuing an Interrupt 
21H. Since this is a call and not an 
interrupt, MS-DOS may place any code 
appropriate to making a system call at this 
position. This makes the process of calling 
the system portable. 


The Disk Transfer Address (DTA) is set to 80H 
(default DTA in the Program Segment Prefix). 


File control blocks at 5CH and 6CH are 
formatted from the first two parameters typed 
when the command was entered. If either 
parameter contained a pathname, then the 
corresponding FCB contains only the valid 
drive number. The filename field will not be 
valid. 


An unformatted parameter area at 81H contains 
all the characters typed after the command 
(including leading and imbedded delimiters) , 
with the byte at 80H set to the number of 
characters. If the <, >, or parameters were 
typed on the command line, they (and the 
filenames associated with them) will not 
appear in this area; redirection of standard 
input and output is transparent to 

' applications. 


Offset 6 (one word) contains the number of 
bytes available in the segment. 


Register AX indicates whether or not the drive 
specifiers (entered with the first two 
parameters) are valid, as follows: 


o AL=FF if the first parameter contained an 
invalid drive specifier (otherwise AL=00) 


o AH=FF if the second parameter contained an 
invalid drive specifier (otherwise AH=00) 


Offset 2 (one word) contains the segment 
address of the first byte of unavailable 
memory. Programs must not modify addresses 
beyond this point unless they were obtained by 
allocating memory via the Allocate Memory 
system call (Function Request 48H). 


2. 


3. 


For Executable (.EXE) programs: 


DS and ES registers are set to point to the 
Program Segment Prefix. 


CS, IP, SS, and SP registers are set to the 
values passed by MS-LINK. 


For Executable (.COM) programs: 


All four segment registers contain the 
segment address of the initial allocation 
block that starts with the Program Segment 
Prefix control block. 


All of user memory is allocated to the 
program. If the program invokes another 
program through Function Request 4BH, it must 
first free some memory through the Set Block 
(4AH) function call, to provide space for the 
program being executed. 


The Instruction Pointer (IP) is set to 100H. 


The Stack Pointer register is set to the end 
of the program's segment. The segment size at 
offset 6 is reduced by 100H to allow for a 
stack of that size. 


A word of zeros is placed on top of the stack. 
This is to allow a user program to exit to 
COMMAND.COM by doing a RET instruction last. 
This assumes, however, that the user has 
maintained his stack and code segments. 


5. .EXE FILE STRUCTURE AND LOADING 
The .EXE files produced by MS-LINK consist of two 
parts: 
o Control and relocation information 
o The load module 
The control and relocation information is at the 
beginning of the file in an area called the 
header. The load module immediately follows the 


header. 


The header is formatted as follows. (Note that 
offsets are in hexadecimal.) 


OFFSET CONTENTS 
00-01 Must contain 4DH, 5AH. 


02-03 Number of bytes contained in last page; 
this is useful in reading overlays. 


04-05 Size of the file in 512-byte pages, 
including the header. 


06-07 Number of relocation entries in table. 
08-09 Size of the header in 16-byte paragraphs. 


This is used to locate the beginning of 
the load module in the file. 
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0A-OB 


0C-OD 


OE-OF 


10-11 


12-13 


14-15 


16-17 


Minimum number of 16-byte paragraphs 
required above the end of the loaded 


program. 


Maximum number of 16-byte paragraphs 
required above the end of the loaded 
program. If both minalloc and maxalloc 
are 0, then the program will be loaded as 
high as possible. 


Initial value to be loaded into stack 
segment before starting program execution. 
This must be adjusted by relocation. 


Value to be loaded into the SP register 
before starting program execution. 


Negative sum of all the words in the 
file (checksum) . 


Initial value to be loaded into the IP 
register before starting program 
execution. 


Initial value to be loaded into the CS 
register before starting program 
execution. This must be adjusted by 
relocation. 


Relative byte offset from beginning of 
run file to relocation table, 


The number of the overlay as generated 
by MS-LINK. 


The relocation table follows the formatted area 
described above. This table consists of a 
variable number of relocation items. Each 
relocation item contains two fields: a two-byte 
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offset value, followed by a two-byte segment 
value. These two fields contain the offset into 
the load module of a word which requires 
modification before the module is given control. 
The following ‘steps describe this process: 


1. 


2. 


The formatted part of the header is read into 
memory. Its size is 1BH. 


A portion of memory is allocated depending on 
the size of the load module and the allocation 
numbers (0A-OB and 0C-0D). MS-DOS attempts to 
allocate FFFFH paragraphs. This will always 
fail, returning the size of the largest free 
block. If this block is smaller than minalloc 
and loadsize, there will be no memory error. 
If this block is larger than maxalloc and 
loadsize, MS-DOS will allocate (maxalloc + 
loadsize). Otherwise, MS-DOS will allocate 
the largest free block of memory. 


A Program Segment Prefix is built in the 
lowest part of the allocated memory. 


The load module size is calculated by 
subtracting the header size from the file 
size. Offsets 04-05 and 08-09 can be used for 
this calculation. The actual size is 
downward-adjusted based on the contents of 
offsets 02-03. Based on the setting of the 
high/low loader switch, an appropriate segment 
is determined at which to load the load 
module. This segment is called the start 


segment. 


The load module is read into memory beginning 
with the start segment. 
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The relocation table items are read into a 
work area. 


Each relocation table item segment value is 
added to the start segment value. This 
calculated segment, plus the relocation item 
offset value, points to a word in the load 
module to which is added the start segment 
value. The result is placed back into the 
word in the load module. 


Once all relocation items have been processed, 
the SS and SP registers are set from the 
values in the header. Then, the start segment 
value is added to SS. The ES and DS registers 
are set to the segment address of the Program 
Segment Prefix. The start segment value is 
added to the header CS register value. The 
result, along with the header IP value, is the 
initial CS:IP to transfer to before starting 
execution of the program. 
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APPENDIX A: BIOS IOCTL SEQUENCES 


MS-DOS 2.1 is able to pass information to and from 
device drivers through the I/O Control (IOCTL) 
function call. 


The data structure used allows data to be 
transferred in both directions with a single IOCTL 
call. When the call is made, the DS:DX register 
pair should be a pointer to the structure, as 
follows: 


DS:DX --> | Type | Status | Device driver information 


Oe 0 a ee NY HS SE er 


The elements of the data structure have the 
following definition: 


o Type -—— WORD value that defines the operation 
to be performed. 


o Status — WORD value that indicates the return 
status of the operation. 


o Device driver information — The device- 
dependent information that is being transferred 
to or from the device driver. 


All future IOCTL enhancements should use this data 
structure. 


A.l SPECIFIC IMPLEMENTATION FOR VICTOR DISK 
DRIVERS 


Get_Disk Drive Physical Info: This function is 
used to get physical information about the disk 
drives on a particular system. The registers 
should get the following values: 


AH —— IOCTL function number (44h) 

AL -—- IOCTL device driver read request 
value (4) 

BL -- drive (0 =A, 1=B, etc.) 

CX -—- length in bytes of this request 
structure (6) 

DS:DX -- pointer to data structure 


For this function, the data structure is: 


DS:DX -—-> | Type | Status | Disk Type | Disk Location 
' 


Disk_Type and Disk_Location are both BYTE values. 
The DOS will return from the IOCTL function with 
carry set if there are bad values in the registers 
(e.g., an invalid drive value). If carry is 
clear, then the request was successful. 


When the request is made, the elements of the data 
structure should have the following values: 


Type = 10h 

Status = Any Value 
Disk Type = Any Value 
Disk Location = Any Value 


After returning from the request, the elements of 
the data structure have the following values: 


Type = unchanged 
Status = 0 if the request type was 
correct (i.e., if Type was 
10h on entry) 
Disk Type = 0 if the drive is a floppy 
drive 
= 1 if the drive is a hard drive 
volume 
Disk Location (meaningful only if Disk Type 
is floppy) 
0 if drive is on the left side 
of the machine 
1 if drive is on the right 
side of the machine 


Il 


To implement other IOCTL device channel functions, 
define Type to have a different value. A Type 
value of 10h should always indicate an IOCTL 

Get _ Disk Drive Physical info request. Currently, 
Type values of 0 - F are reserved for future use. 


A.2 SPECIFIC IMPLEMENTATION FOR INTERFACE PORT 
ACCESS 


TYPE 


For port access via IO Control, the type is always 
ll hexadecimal. The parameter block types 
determine which port type is being accessed (i.e., 
parallel or serial). 


STATUS 


Status is returned to reflect if an error 
occurred. An error could occur when an incorrect 
type or an invalid function is being requested. 
Status contains the code describing the cause of 
the error. If an error does not occur, status is 
returned as false (0). Currently, the only codes 
used for serial port access are: 


01 -when an invalid function is being requested. 
-]1 -when an invalid type is being requested. 


PARAMETER BLOCK 


The first word of the parameter block for port 
access should always be the parameter block type. 
This is used to notify the driver of the structure 
of the parameter block that follows. 


Parameter block.type (WORD) 

—Describes the type 
of port being 
accessed. 

Serial = 0 
Parallel = 1 
SERIAL 


The structure definition Of the serial port IO 
control parameter block is as follows: 


Baud (2 bytes) 


These bytes must be set according to Table A-l. 


Table A-l: Definition of Serial Port IO Control 
Parameter Block 


BAUD LOW BYTE HIGH BYTE 
50 lah 06h 
75 lih 04h 
110 céh 02h 
134.5 44h 02h 
150 08h 02h 
200 86h O1lh 
300 04h Olh 
600 82h 00h 
1.2k 41h 00h 
1.8k 26h 00h 
2.0k 27h 00h 
2.4k 20h 00h 
3.6k 15h 00h 
4.8k 10h 00h 
9.6k 08h 00h 
19.2k 04h 00h 


For the following, refer to the Technical 
Reference Manual for the bit format of the bytes. 


CR control (byte) Control register 0 
Interrupt enable (byte) Control register 1 


Interrupt mode (byte) Control register 2 


(channel A) 
Interrupt vector (byte) Control register 2 

(channel B) 
Receiver (byte) Control register 3 
Sampling (byte) Control register 4 


A-5 


Transmitter (byte) Control register 5 
SYNC character (byte) Control register 6 
SYNC character (byte) Control register 7 


Via 10 control, two operations can be performed on 
the serial ports. You can set the port for a 
certain configuration and you may request the 
current port configuration. IO control functions 
2 and 3 (read and write) perform the operations 
respectively. When a request is made to set the 
port, the configuration information is saved. 
Then if the current configuration is requested the 
parameter block last used to set the port is 
returned to you. 


To use IO control, the following register 
initializations have to be made before performing 
an MS-DOS INT 21h: 


AH = JOCTL function number (44h) 

AL = IOCTL write request (3) or IOCTL read 
request (2) 

CX = length in bytes of information structure 


(9) 


DS:DX = pointer to the information structure 


PARALLEL 


The driver for the parallel port is the currently 
used driver; but functionally is added to return 
extended statuses such as printer out of paper, 
and printer offline. 


The parameter block has the following structure: 
prameter block type WORD, 
status code WORD 


Only the status codes listed are implemented, but 
other codes may be added as necessary. 


0 Online and ready 
1 Offline 
2 Out of paper 


To use IO control, the following register 
initializations have to be made before performing 
an MS-DOS 21h. 


AH = IJOCTL function number (44h) 

AL = IOCTL read request (=2) 

CX = Length in bytes of information 
structure 

DS:DX = pointer to the information structure 
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